
                                 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.

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 or /tmp/.private only.  This is a security sensitive parameter.
   System administrator can change this default, either systemwide or
   personally for you.
   In first case, change parameter "prefix" in systemwide config
   file /etc/hasher-priv/system to /path/to/workdir.
   In second case, add the line
	prefix=/path/to/workdir
   to per-user config file /etc/hasher-priv/user.d/$USER.

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

4. HOW TO?

4.1. Parallel build.

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

   Yes, there 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, there is.

   First, hasher-priv should be configured to allow mounting /proc inside
   chroot, either systemwide or personally for the user.  Add the line
	allowed_mountpoints=/proc
   either to systemwide config file /etc/hasher-priv/system or
   to per-user config file /etc/hasher-priv/user.d/$USER.

   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, there is.

   First, hasher-priv should be configured to allow terminal device files
   creation and mounting /dev/pts inside chroot, either systemwide or
   personally for the user.  Add two lines:
	allow_ttydev=yes
	allowed_mountpoints=/dev/pts
   either to systemwide config file /etc/hasher-priv/system or
   to per-user config file /etc/hasher-priv/user.d/$USER.

   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, there 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.
