
                                 The hasher FAQ

                           Frequently Asked Questions
                            about the package hasher

CONTENTS

1. GENERAL INFORMATION
1.1. Introduction - How this FAQ is organized
1.2. Credits and acknowledgements
1.3. Standard disclaimers

2. BASIC HASHER
2.1. What is hasher?
2.2. What is hasher not?
2.3. Where can I learn more about hasher?

3. WHY ISN'T THIS WORKING?
3.1. Problems accessing privileged helpers.
3.2. Workdir prefix mismatch.
3.3. Local and remote repositories.

4. HOW TO?
4.1. Parallel build.
4.2. Proc filesystem and pseudo terminals.
4.3. Native shell.

------------------------------

1. GENERAL INFORMATION

1.1. Introduction - How this FAQ is organized

   This FAQ is organized to answer common (and some uncommon)
   questions about hasher, quickly.

1.2. Credits and acknowledgements

   The following individuals have contributed significantly to this
   document, and have provided input and wording suggestions for
   questions, answers, and examples.  Credit goes to these contributors
   (in alphabetical order by last name):

1.3. Standard disclaimers

   While a serious attempt has been made to ensure the accuracy of the
   information presented herein, the contributors and maintainers of this
   document do not claim the absence of errors and make no warranties
   on the information provided.  If you notice any mistakes, please let
   us know so we can fix it.

------------------------------

2. BASIC HASHER

2.1. What is hasher?

   Hasher is modern safe package building technology.
   In general, it inputs source package and outputs binary packages.

2.2. What is hasher not?

   Hasher is for package build only.  It is neither package repository
   (in spite of the builtin repository it maintains) nor universal chroot
   creation tool (in spite of the build environments it generates).

2.3. Where can I learn more about hasher?

   There is a hasher(7) manpage which describes hasher architecture.
   It references to other useful manpages you might want to study.
   There is a README file nearby.
   And, of course, there is a Google.

------------------------------

3. WHY ISN'T THIS WORKING?

3.1. Problems accessing privileged helpers.

3.1.1 How to make hasher work? Every run ends up with the following:
	Components: hasher
	Processing pkglists... hasher done
	Processing srclists...  hasher done
	Creating component releases... hasher done
	Creating global release file... done
	Appending MD5Sum... hasher done
	All your base are belong to us!!!
	hsh-mkchroot: cannot access getugid1 helper.

  In order to prepare package hasher to use by USER, pair of special
  satellite users must be added.  System administrator should run
	# hasher-useradd USER

  This command creates two additional satellite users, USER_a and
  USER_b, and adds USER to groups: hashman, USER_a and USER_b.

  See hasher-useradd(8) for details.

3.1.2 I've created satellite users according to instructions, but still
   getting the same error.  Why?

   You have to re-login to gain new credentials.

3.1.3 Well, I've logged in, now it reports:
	hasher-priv: /: bad perms: 757
	hsh-mkchroot: getugid1 failed.

   You file system permissions are broken, you really should repair your
   operating system as soon as possible.

3.2. Workdir prefix mismatch.

3.2.1 When I run
	hsh /path/to/workdir path/to/package.src.rpm
      hasher fails with:
	hasher-priv: /path/to/workdir/chroot: prefix mismatch, working directory should start with $HOME
	hsh-mkchroot: failed to make devices.

   By default, hasher is configured to create working directories
   inside $HOME only.  This is a security sensitive parameter.  System
   administrator can change this default, either systemwide or personally
   for you.
   In first case, change "prefix" parameter in
   /etc/hasher-priv/system to /path/to/workdir.
   In second case, add the line
	prefix=/path/to/workdir
   to the per-user config, /etc/hasher-priv/user.d/$USER.

3.3. Local and remote repositories.

3.3.1 Run of hasher failed with the following error:
	hsh-initroot: calculated package file list is not local and apt-get does not support APT::Get::PrintLocalFile option.
	hsh-initroot: failed to generate initial package file list.

   Hasher is designed primarily to work with local repositories.  There is
   a limited support for remote repositories implemented using apt-get
   APT::Get::PrintLocalFile option.  This option is available in
   apt >= 0.5.15cnc6-alt18.

------------------------------

4. HOW TO?

4.1. Parallel build.

4.1.1 Is there any way to build packages in different locations
   simultaneously?

   Yes, it is.

   First, additional pseudouser pairs should be created by hasher-useradd
   for each additional parallel build.
   Second, you have to pass subconfig identifier to hsh.

   For example,
   # hasher-useradd --number=1 --names=joe_a1:joe_b1
   $ hsh --number=1 /path/to/workdir1 package.src.rpm

4.2. Proc filesystem and pseudo terminals.
 
4.2.1 Is there any way to use proc filesystem inside chroot while building
   the package?

   Yes, it is.

   First, you have to configure hasher-priv for the user, to allow
   mounting /proc inside chroot.
   Add the line:
	allowed_mountpoints=/proc

   Second, the package you are going to build should include /proc
   in its build dependencies, e.g.
	BuildPreReq: /proc
   Alternatively, at least one of packages installed to build environment
   should include /proc in its dependencies.
 
   Third, hsh should be run with parameter --mountpoints=/proc.

4.2.2 Is there any way to create pseudoterminals and use them inside
   chroot while building the package?

   Yes, it is.

   First, you have to configure hasher-priv for the user, to allow
   terminal device files creation and mounting /dev/pts inside chroot.
   Add two lines:
	allow_ttydev=yes
	allowed_mountpoints=/dev/pts

   Second, the package you are going to build should include /dev/pts
   in its build dependencies, e.g.
	BuildPreReq: /dev/pts
   Alternatively, at least one of packages installed to build environment
   should include /dev/pts in its dependencies.
 
   Third, hsh should be run with parameter --mountpoints=/dev/pts.

4.3. Native shell.

4.3.1 Is there any way to run shell with normal terminal inside chroot?

   Yes, it is.

   You should understand that building packages and running shell are
   incompatible tasks.  Hasher is devoted for the first one, however
   you can use it for the second one, too.

   For example, this command
   $ hsh-shell
   will run bash as login shell with stdin, stdout and stderr associated
   to pseudoterminal created by hasher.

   If user is allowed to create tty devices and mount /dev/pts inside
   build chroot, this command
   $ hsh-shell --mountpoints=/dev/pts
   will create tty devices and mount /dev/pts inside build chroot,
   execute bash as login shell with stdin, stdout and stderr associated
   to pseudoterminal created by hasher, and after bash exit this command
   will remove created devices and unmount /dev/pts from the chroot.
