krack(1)

NAME

krack - A set of programs for building, uploading, and receiving packages

OVERVIEW

"Krack" comprises several programs: krack-build, krack-receive, and krackctl.

Krack-build is designed to run on one computer, which will build packages and send them over rsync to another computer: the receiving computer, where krack-receive runs as a daemon that watches a directory for new packages to add to a pacman repo.

The specific use case krack is built for, is having a PC at home which can build packages, and having a pacman repo hosted on a receiving low-cost, low-power remote VPS.

Builder PC (home) | Receiver PC (VPS)
Runs krack-build and uploads packages | Runs krack-receive and hosts packages

  KRACK-BUILD

Krack-build is the largest program of the bunch and will run via a systemd service triggered periodically by a systemd timer on the building PC, running as a user specifically made for building and sending packages. It will create a directory ~/.local/share/krack/ in the invoking user's home directory. Under this directory, several more are created:

•   logs/, for holding logs automatically created by krack-build;
•   packages/, for holding package directories containing PKGBUILDs and other source files (referred to henceforth as the "package directory"); and
•   pkgcache/, for holding the latest built packages.

The logs/ directory will be filled with logs containing the entirety of krack-build's output, including all of makechrootpkg's output. These logs can grow quite large, so krackctl can help you parse these logs easily and get a good feel for the health of your running krack-build instance. You can read more about krackctl in READING LOGS.

You should fill the package directory with other directories, each containing PKGBUILDs and other build files, as if just cloned from the AUR. If you have personal packages, you can symlink them from other directories into krack-build's package directory and krack will treat them as any other package, but be aware that krack-build will run commands in these directories and may change files. Krack-build can also handle packages from the Arch Build System.

The pkgcache/ directory will contain the latest built package for every package in the package directory, if it has been built at least once.

Immediately after krack-build starts, it will clean out the package directory of old build files, and update the Arch chroot. Next, each package will be checked to see if it needs to be built.

Krack-build will only initiate an individual package build if at least one of three circumstances is met:

1.  New commit(s) were pulled in via "git pull"
2.  The package name ends in "-git"
3.  The file "krack-request-build" exists in the package's directory

Krack-build will always upload a newly built package, unless a package with the same filename (and therefore version) exists in the local pkgcache/ directory.

  KRACK-RECEIVE

Krack-receive will run as a systemd service on the receiving system that hosts a pacman repository. Krack-receive will watch for new packages to add to the specified REPO_ROOT (directory of pacman repository). The path of your pacman repo, as well as the database filename, should be specified in /etc/krack/receive.conf on the receiving PC. Krack-receive does NOT create a pacman repo or make the package files available over the internet; you must set up the repo and HTTP server yourself with other software.

See man krack-receive for more details.

  KRACKCTL

Krackctl can be used on the builder PC, as the builder user, to control the running krack-build instance. See man krackctl for a full list and explanation of available commands.

SETUP

  RECEIVER PC

If you haven't yet already, set up a pacman repository at the desired directory on your receiver PC. You can then host this directory with an HTTP server like Nginx or Apache. The instructions for both of these steps are outside the scope of this man page.

After that, you will need to create a user with the username "krack-receive" specifically for receiving packages. Ensure that you can ssh into this user, via SSH keys, from your builder user on the builder PC. Create a directory "package-dropbox" in this user's home directory (/home/krack-receive/package-dropbox/) where packages will be rsync'ed to from the building PC.

WARNING! You MUST:

•   name the user "krack-receive" or the systemd sandboxing will render the service broken.
•   create the dropbox directory at "~/package-dropbox" or krack-receive will not work at all.
•   ensure the hosted pacman repository directory and all files within are owned by the krack-receive user/group.

WARNING: ssh may refuse to work unless you give the 'krack-receive' user a password.

Edit /etc/krack/receive.conf with your specific paths:

•   $REPO_ROOT should be where the pacman repo is that you set up earlier.
•   $REPO_DB_FILE is the name of the database file for the repo, e.g. reponame.db.tar.

Finally, enable and start krack-receive.service.

→ Note that the krack-receive systemd service configuration mounts /usr and /etc as read-only. If your pacman repository resides in one of these directories, you will need to add a drop-in conf file for the krack-receive systemd service that allows read/write access to your pacman repository path.

  BUILDER PC

First, you will need to make an Arch chroot for building packages. You can create one with the command sudo krackctl create-chroot on a user on your builder PC with sudo privileges. Alternatively, you can create one manually with the mkarchroot command. If you choose to do it manually, make sure to install the base-devel and ccache packages in the chroot.

Next, you will need to create a user specifically for krack-build on the builder PC. You can name this user whatever you want to, but "builder" is a good default. You will also need to create a GPG and an ssh key on this user, for signing and uploading packages respectively. Ensure you can ssh from your builder user on your builder PC to your receiving user on your receiving PC. Ensure you can sign files with your new GPG key.

You will need to set up sudo permissions such that your builder user can use makechrootpkg and arch-nspawn (to update the build chroot) without having to enter a password. Additionally, as of devtools-20211129, you must allow your builder user to keep the BUILDTOOL and BUILDTOOLVER environment variables when using sudo. You can do this by adding the following lines to /etc/sudoers:

    builder-user ALL=(ALL) NOPASSWD:/usr/bin/makechrootpkg, /usr/bin/arch-nspawn
    Defaults:builder-user env_keep += "BUILDTOOL BUILDTOOLVER"

Change builder-user in both lines to the name of your builder user you chose earlier.

Finally, you will need to edit /etc/krack/build.conf for your specific setup:

•   $MAKECHROOTPKG_DIR is the location of the Arch chroot that will be used to build packages. /var/lib/makechrootpkg is where sudo krackctl create-chroot will create the Arch chroot by default.
•   $SIGNING_KEY should be the GPG key ID of the signing key you wish to use, in the builder user's keyring that you created earlier.
•   $DROPBOX_PATH is the path to the remote PC using rsync HOST syntax, e.g. 173.195.146.142. Do not include any directories, only the host.

  LAST STEP

Krack-build runs automatically via a systemd timer. You can start it with the command systemctl enable --now krack-build@builder-user.timer. Make sure to replace builder-user with the name of your builder user you chose.

If you run systemctl status krack-build@builder-user.service, it should be napping, since you haven't added any packages to the krack package directory.

As the builder user, navigate to ~/.local/share/krack/packages. Here you can add package directories, either by cloning from the AUR or copying or linking package directories from somewhere else in your file system. The directory structure should look like this, for example:

    ~/.local/share/krack/packages/
     |
      \-- babl-git/
          |-- PKGBUILD
     |
      \-- gegl-git/
          |-- PKGBUILD
          |-- example.install
     |
      \-- gimp-git/
          |-- PKGBUILD
          |-- ...

You can now run systemctl restart krack-build@builder-user.service, and it will start building and uploading packages. See man krackctl for more commands.

You can now log out of or reboot your builder PC; the krack-build timer will persist through reboots and continually re-build packages on a regular interval. To specify how and when the timer is run, see SYSTEMD-FEATURES below.

OTHER

  READING LOGS

Krack has several useful ways for you to view and parse logs.

You can run krackctl status on the builder PC to get a good overview of your current running krack-build instance. Using the built-in log system, it will display the current state (e.g. sleeping, building, ...), the current substate if there is one (e.g. building gimp-git), the latest 10 important messages from most to least recent, the filename of the current log file, and the last 10 lines of raw output from the running krack-build instance. krackctl watch-status does the same thing, but refreshes every second and fills the entire terminal.

If krack-build pulls in new commits during the "git pull" part of the build process, it will save the output of the diff between the new commit and the old commit to a file. Diffs can be listed with the command krackctl list-diffs.

Each time krack-build starts building a package, it saves the full output of the makechrootpkg command for that package build to a temporary log file. If the makechrootpkg command fails, the temporary file is made permanent at ~/.local/share/krack/logs/failed-builds. Only the latest failed build log is saved for a given package, so if you leave krack unattended for a few build cycles and a package fails to build a few times, you won't be overwhelmed with multiple failure logs.

Failed build logs can be listed with the command krackctl failed-builds. You can use your favorite pager to view these files.

You can view the full log files in ~/.local/share/krack/logs. They contain the entire output of the krack-build instance they were generated from, including all makechrootpkg output for every package. By default, after each build cycle, the log from that cycle is compressed with brotli.

Since both krack-build and krack-receive run as systemd services, you can use journalctl commands to view and parse the full log.

  BUILD HOOKS

Krack-build supports custom build hooks. The build process for each package occurs in the following steps:

1.  cd into package directory
2.  * source krack-prepull.sh, if it exists
3.  git checkout PKGBUILD, in case the last build of the package changed it in any way
4.  git pull
5.  * source krack-postpull.sh, if it exists
6.  makechrootpkg
7.  * source krack-postbuild.sh, if it exists

You can put any valid Bash in all krack*.sh scripts, and they will be sourced by krack-build at the indicated step in the build process. These scripts can be used for many things, such as patching PKGBUILDs or other source files. But be careful! Since krack-build is sourcing your scripts, if you cd anywhere, krack-build will too. And if you patch files other than the PKGBUILD, make sure to git checkout them out again in krack-prepull.sh if you want to avoid build failures when attempting to merge incompatible files during git pull in the build process. (However, this is not always desirable -- you may wish to be notified of incompatible files this way if you want to update your patche(s) to accomodate new changes, if these files are not updated frequently enough to be a nuisance.)

These scripts should be placed in the package directory that they are affecting.

  SYSTEMD FEATURES
By using systemd to run krack-build, you can greatly customize how and when the service runs. Run the command systemctl edit --full krack-build@.timer.

Change the following snippet:

    [Timer]
    OnBootSec=2m
    OnUnitInactiveSec=20h

To how and when you would like systemd to trigger the timer. For example, to build twice a week, on Tuesday and Friday, at 2:30am:

    [Timer]
    OnCalendar=Tue,Fri *-*-* 2:30:00

You can also use systemd to restrict how much of the system resources are used for package building. To add a drop-in conf file to the krack-build service, run the command systemctl edit krack-build@.service. For example, the following file:

/etc/systemd/system/krack-build@.service.d/restrict-resources.conf
    [Service]
    AllowedCPUs=0,1
    Nice=19
    IOSchedulingPriority=7

...would restrict krack-build to only the first two logical CPUs and have lower priority process and IO scheduling. This may be useful if you run other services on your builder PC and want to prioritize those services before krack-build. See man systemd.resource-control and PROCESS PROPERTIES in man systemd.exec for other ways to limit system resources.

After editing, make sure that you run systemctl daemon-reload for systemd to pick up the changes.

  EMAIL NOTIFICATIONS

Krack-build can be configured to email the final build cycle report to a specified email address. The 'msmtp' program will be used to send emails. Configure /etc/krack/build.conf with your preferrend send/receive address, and for the builder user, configure ~/.msmtprc with your email server/login information.

An example build.conf snippet looks like this:

    readonly EMAIL_CYCLE_REPORT="true"
    readonly EMAIL_FROM_ADDR="builder@krathalan.net"
    readonly EMAIL_TO_ADDR="admin@krathalan.net"

And a matching example ~/.msmtprc:

    account builder
    host krathalan.net
    port 465
    from builder@krathalan.net
    auth on
    user builder
    password XXXXXXXXXXXXXXXXX
    tls on
    tls_starttls off
    logfile ~/.msmtp.log
    account default : builder

  CCACHE COMPLIANCE

If ccache is enabled in the builder PC's /etc/makepkg.conf and the builder PC's $MAKECHROOTPKG_DIR/root/etc/makepkg.conf, and the ccache package is installed on both the builder PC and the builder PC's $MAKECHROOTPKG_DIR/root, krack-build will handle creating and binding the CCACHE_DIR on both the builder PC and chroot.

  SSH SETTINGS

If your receiver PC's sshd uses a custom port, you can specify it in ~/.ssh/config on the builder user. For example:

    ~/.ssh/config
    -------------
    Host krathalan.net
            Port 37457
    Host 168.200.255.199
            Port 9238

SEE ALSO
krackctl(1), krack-build(1)

BUGS

Please file requests, suggestions, and report any bugs at: https://codeberg.org/krathalan/krack/issues

LICENSES

All krack programs are licensed under the GPLv3.