Urpkg User Manual

You need a UNIX-like system for urpkg to work. I have tested it on GNU/Linux (LFS and Slackware 12.1), but other systems should work as well. You will also need root access on that system. By design, urpkg is useless if you cannot get root access, since it needs to be able to create new users to install a package. Some scripts assume that your user list is in /etc/passwd and your group list in /etc/group. If that is not the case, you should change them accordingly.

First, extract the urpkg tarball and cd to it.

    $ tar -xf <Your .tar.gz file>
    $ cd <filename without .tar.gz>
  

Then, you should create a build directory

    $  mkdir build
    $  cd build
  

Now it is time to configure your build. The command is of the form

In general, you should not need to set a lot of variables. A simple

    $ cmake ..
  

should be enough. The possible variables and their default values are listed below.

Now everything should be ready. Compile the program.

    $ make
  

If you want to compile the documentation as well (if you downloaded a release tarball that should not be necessary, as it has already been compiled to most format for you), run

    $ make doc
  

To install urpkg, you have two choices: the first is to directly run

    $ make install
  

with root privileges if necessary. However, if you have read all I said in the section called “How can urpkg be useful ?” about installation programs changing file permissions behind your back, you may not even want to trust the installation commands generated by cmake.

This is perfectly fine. Since you have compiled urpkg, you can use it to install itself in a secure way. The following section lists the necessary steps. I recommend this method only to users already familiar with how urpkg works. If you are doing this often, you should write yourself a script that automates this action. One such script is in helpers/bootstrap.sh in the top level directory of urpkg's source.

      $ cd build/
    

      $ mkdir ${PKGDIR}
    

      $ groupadd urpkgrp-install
      $ groupadd urpkgrp-shared
      $ src/urpkg --gen ${CMAKE_INSTALL_PREFIX}/bin
      $ src/urpkg --gen $DOCDIR
      $ src/urpkg --gen ${MANDIR}/man*
      $ src/urpkg --gen $(dirname $CONFIGDIR)
    

      $ PKGDIR="$(mktemp -d /var/tmp/urpkg.XXXXXXX)"
    

      $ chmod -Rv o+xrw .
    

      $ src/urpkg --install --pkg-name=urpkg-$VERSION \
      --findcmd=../scripts/find --pkg-dir=$PKGDIR --no-preinst --no-postinst \
      make install
    

      $ urpkg --info
    

      $ cp -rav ${PKGDIR}/urpkg-$VERSION $TRUE_PKGDIR
    

      $ USERNAME="$(stat --format=%U ${TRUE_PKGDIR}/urpkg-$VERSION)"
    

      $ usermod --home ${TRUE_PKGDIR}/urpkg-$VERSION $USERNAME
      $ rm -rv $PKGDIR
    

We will create two destination directories. One where the program will be allowed to be installed, and one where it should not write any files. We will create those directories in /usr/urpkg-test, or any other directory you wish (just be sure that it is not listed in the EXCLUDE variable of the find command). We will assume /usr/urpkg-test/ has been chosen.

    $ cd /usr
    $ sudo mkdir urpkg-test
    $ cd urpkg-test
    $ sudo mkdir allowed
    $ sudo mkdir restricted
  

Now we put some files in the two directories. Those files should not be overwritten by our test package.

    $ sudo touch allowed/{file1,file2}
    $ sudo touch restricted/{file1,file2}
  

Let's name our package foo, and create some files in it.

    $ sudo mkdir foo
    $ sudo touch foo/{foo1,file2}
    $ cd foo
  

Let's say that foo1 is specific to the package foo, while file2 is a more recent version of allowed/file2. So we would like to overwrite allowed/file2 with foo/file2 . The installation command will be given to urpkg in the next chapter.

The preinstall script should be in ${CONFIGDIR}/preinst, by default /usr/local/etc/urpkg/preinst. The default script that comes with the urpkg tarball does not run any command. It is up to you to change it if you want certain command to be run before any package is installed. Pay attention though, because this script will be invoked with the same privileges you had when you invoked urpkg. They will not be run as the package user. If you want to exclude the preinstall script from being run, you have to use the --no-preinst option.

Every postinstall script should be put in ${CONFIGDIR}/postinst/, by default /usr/local/etc/urpkg/postinst/. Every script here is run after the installation. The scripts are run in an undefined order. By default, ldconfig and a script installing the program's source are run.

The source script is run only if it is passed the source files as an argument. To pass an argument to a postinstall script, use --SCRIPT-arg. For example, if the sources of foo are in a foo.tar.gz file, you would do

    $ sudo urpkg --install --source-arg=foo.tar.gz make install
  

The sources are installed in the package directory, in src/. For a package named foo-1.1 that would be ${PKGDIR}/foo-1.1/src

You can use the --no-postinst option to not run any postinstall script or --exclude-script to exclude a particular one.

We already know we can use the --list action to list all files which are part of foo. However, what is outputted does not only contain files, as list2pkg require. We must add the --quiet option for a “pure” list of files to be generated.

That's all we need. We now only have to use the file listing command, and pipe its output to list2pkg.

    $ urpkg --list --quiet foo | sudo list2pkg foo-0.1-noarch-1usr.tgz
  

Note that we absolutely need to invoke list2pkg with root privilege, in order for all metadata to be preserved.

However, urpkg first has to come up with a name for this user. The name should conform to the syntax of a username (e.g, no dot in the name) and should not be the same as other users in the system. One could simply come up with a unique number as username, however that would be really confusing and not really helpful e.g to someone listing a file belonging to that package.

The solution that urpkg uses is the following. We ask the user for, or guess, a package name that is basically the name of the program we are installing. This name can syntactically be anything the user wants. Then, from that name we generate a package user name. The package name is kept in the comment field of the user name in /etc/passwd.

The package user name always begins with “urpkg-”. This is a prefix to avoid that the name collides with another user of the system. Urpkg then generates the rest of the username using the beginning of the package name, and adding some numbers if necessary. You should look at the source if you want more details on the exact algorithm which is used. Special characters in the package name are replaced by “_”. For example, from a package name “emacs-22”, the package user could be “urpkg-emacs-22”. You shouldn't rely on this, however, as the algorithm used by urpkg to generate user names can change at any release without notice !

Note that package names (and package users) are always all in lowercase letters. Even if you give your name explicitly, the case does not matter and your name will automatically be converted to lowercase. For example, running

    $ urpkg --install --pkg-name=Emacs-22 make install
  

Will still create a package name “emacs-22” and a package user “urpkg-emacs-22”.

In general, you don't have to worry about package users, but it's good to know about them, as you can still see them mentioned from time to time. For example, assuming you really have emacs installed as a package named emacs-22, doing

    $ ls -l $(which emacs)
    -rwxr-xr-t 2 urpkg-emacs-22 urpkg-emacs-22 13576490 2008-03-21 17:59 /usr/bin/emacs
  

will really give you the package user name of the package the file /usr/bin/emacs belongs to.

As you learned in the previous chapter, you can specify a package name explicitly using --pkg-name. Urpkg can also guess a package name for you from the current directory. Now how does it do it ?

Urpkg will simply take the basename of your current directory (i.e if your current directory is /var/tmp/emacs-22.1, the basename is emacs-22.1). It will then check if it has a version string. A version string is defined as anything following a dash (-). In our example, there is a version string so the package name would be “emacs-22.1”. If there is no version string, urpkg will append one with the date in the following format: YYYYmmdd. For example, if you are developing your own program, foo which is in a directory /var/tmp/foo, then if you install it on June, 30th 2010 the package name will be “foo-20100630”.

Of course, there cannot be two package with the same name installed on the system, so urpkg will signal an error if you try to give a package name which is already the name of an existing package.

Now that we have created a user for the package, we still have to decide where it has permission to write. This is done, as seen previously, using the --gen option. Ideally, we would like the package not to be able to overwrite other package files in the install directories, nor remove them. There is a permission bit on UNIX systems that achieve just that: the sticky bit.

The sticky bit prevents unprivileged user (i.e the package user in our case) from changing or removing a file that they don't own. It is typically used in directories like /tmp, where everyone has write access.

The idea is that you are going to give write access in the install directory to all package users, but since the sticky bit is on, they won't be able to damage files from other packages.

How do we give write access to all package users ? In short, we put every package user in a given group, called the install group, as they are created. When --gen is invoked, all urpkg do is to change the directory's group to this install group, enable write access for this group and turn on the sticky bit.

Something similar happens for shared files, although we don't need the sticky bit here, and a different group is used: the shared group.

The install group is “urpkgrp-install” and the shared group is “urpkgrp-group”. Every package user is a member of those groups once it is created. This means it is possible for any package to write to a shared file or put files in an installation directory. Keep this in mind when you make a file shared for example.

As we have already seen, all files created by a package user have by default its name as owner and its group as group. Why do we need to have both ? In fact we don't, for simple cases. As a matter of fact, urpkg will consider any file that has the package user as its owner or as its group. The nice thing about this is that you can easily change the owner or group of any file of the package.

For example, suppose you are installing the sudo program. It obviously needs to be suid root by the very nature of the task it performs. In that case, you can just change its owner to root and set the suid bit as usual. The file will still be detected as belonging to the sudo package since its group still has the package user name of sudo.

Sometimes it may happen that both the group and the owner have to be changed. This is the case for some daemon that uses both the suid and the sgid bit. Fcron is an example of this. In that case, you can still force the file to belong to the package using --add without any --change-owner or --change-group option. The file name will then be added to a text file containing a list of supplementary files belonging to fcron. The disadvantage here is that you cannot move or remove the file without having urpkg complaining, so don't do it unless you really have to. More details are given in the section called “Owned and added files”

This is the script urpkg uses to find files whose owner or group is a given package user. It is also used to list install directories or shared files. It takes one argument: a user or group name. It should print the list of files in the system that are owned by this user or group, excluding the package's home directory

By default, a few locations such as /tmp or /mnt, or the package home directory are excluded from the search. They are given in the EXCLUDE variable at the beginning of the script. Please check that they match your expectation.

It is run before any installation. It takes no argument, and by default does nothing but printing a line or two to confirm it was executed.

All files in the directory postinst relative to the configuration directory will be run after the installation. Each can be passed exactly one argument using the --SCRIPT-arg option.

If you decide to write your own scripts, you can count on several environment variables to help you:

Urpkg considers a file as belonging to a given package if one of the two conditions below is satisfied.

Given this definition, it is easy to see that a file can belong to more than one package. For example, it could have a given package user as its owner , another as its group, and be listed in the added list of a third package. Most of the time though, a file will be only part of one package and you should really keep it that way.

If you use the --find command, urpkg will list you all packages the given file belongs to.

When you use the --list action, urpkg will list you the files that are unique to the given package, and the files that are shared with other packages. Only the former category will be deleted when you uninstall the package. Keep in mind that you can always use --pretend to know for sure what would be removed.

First, urpkg will never remove a directory that does not belong to the package you want to uninstall, even if it is empty. Second, a directory that belongs to the package you are considering must be empty (after you deleted all the other files in it belonging to the package) to be deleted. This prevents other files from other packages that are in the directory to be deleted as well. This can happen if, for example you temporarily set a directory as an install directory and then revert it to belong to the given package.

Urpkg will take no risk and only warn you that the directory is not empty. The uninstallation will not fail just because of that. You will have to remove those directories manually. If you are careful the way you manage your system, this should only happen rarely.