The Ur Project

Documenting the craft of stacking things so they remain stacked. For a very long time.

Basic system maintenance

Here are the topics covered by this shorter user guide on how to administer your Ur Project based Linux OS.

  • Basic updates
  • Installing packages
  • Removing packages
  • Listing installed packages
  • Working with sets and subpackages
  • Performing a roll back, and rolling forward again

Other guides will cover more topics in depth. Refer to them or the Administration documentation section for those topics.

Basic updates

$ sudo pkg upgrade

This is really all there is to doing system updates. The pkg tool takes care of every aspect of package lifecycle management for the user. It will create the required user IDs for daemons and services if they are part of the installed sets. It will create required directories and place configuration files as needed, and it also will remove no longer needed packages from sets.

After installation, you may need to reboot your system, especially if a new kernel version was installed.

Installing packages

$ sudo pkg install luanti

Packages can be found by name easily with the search subcommand, which searches just in the name of the package. Here's an example of that:

$ pkg search route
iproute2                   7.2.0   [/bin, /data]
iproute2/debug             7.2.0
iproute2/debugsrc          7.2.0
iproute2/dev               7.2.0
iproute2/man               7.2.0
rust-netlink-packet-route  0.25.1  [/rustlib]
traceroute                 2.1.6   [/bin]
traceroute/debug           2.1.6
traceroute/debugsrc        2.1.6
traceroute/dev             2.1.6
traceroute/man             2.1.6
traceroute/staticdev       2.1.6

As you can see, the route text matched 3 packages. There are also a few subpackages listed separately, and some are listed combined. More on that in the sets section below.

Removing packages

$ sudo pkg remove emacs

The remove command will attempt to remove emacs. If nothing depends on it, it will be uninstalled. The command will by default ask you to confirm the deletion. This confirmation can be configured for more tasks to be required, or omitted. By default, the confirmation is only needed for destructive operations, like uninstallation of packages.

Sometimes removing a package isn't entirely straightforward, because something is still hanging on to whatever needs to be removed. Here's such an example:

$ sudo pkg remove luanti/data
error: install: resolution failed: cannot remove 'luanti/data': 'luanti/bin' still requires 'package:luanti/data =5.17.0'

The command error indicates that there is still a package that requires that sub package to be present. Thus, we can't directly uninstall it. We could --force uninstall it, but it would leave an orphan.

Instead, we can ask for a cascade removal. It could be dangerous, but, do not worry, by default nothing will get removed without explicit approval from you.

$ sudo pkg remove luanti/data --cascade
Plan:
  remove:
    - luanti         5.17.0-1  [/autostart, /bin, /data]
    - luanti/server  5.17.0-1
  blocked: applying this would be refused by 1 gc check(s) (--force overrides):
  luanti/server: pid 959 maps /usr/bin/luantiserver
error: install: removal blocked by 1 gc check(s); re-run with --force to override:
  luanti/server: pid 959 maps /usr/bin/luantiserver

The cascade worked! It saw that there was one dependent package. And it attempted to perform the uninstallation of both, but that failed due to the fact that a live service still is using the binary files. We have to shut that down first, or, again we could --force the uninstall, leaving a potentially broken service running:

$ pgrep luantiserver
959
$ sudo systemctl stop luanti-server.service

Good, now it should uninstall properly. The daemon will have stopped running.

$ sudo pkg remove luanti/data --cascade
Plan:
  remove:
    - luanti         5.17.0-1  [/autostart, /bin, /data]
    - luanti/server  5.17.0-1
Proceed? [y/N] y
Transaction complete: 0 installed, 4 removed (#7, see `pkg history info 7`)

All good. The package we wanted to remove is now gone.

Listing installed packages

$ pkg list
+console                      -                  Sandcastle-Common  [22/22 members, +21 dependencies]
+firmware-pc                  -                  Sandcastle-Common  [8/8 members]
+gdm-login                    -                  Sandcastle-Common  [24/24 members, +135 dependencies]
+gnome                        -                  Sandcastle-Common  [83/83 members, +203 dependencies]
SDL2                          2.32.10-2          Sandcastle-Common  [/lib]
audit                         4.2.1-4            Sandcastle-Base    [/bin]
avahi/server                  0.8-7              Sandcastle-Common  [root, +26 dependencies]
bash-completion               2.18.0-3           Sandcastle-Common  [/data]  [root]
blktrace                      1.3.0-4            Sandcastle-Common  [/bin]  [root, +2 dependencies]
boot-manager                  0.0.13-3           Sandcastle-Common  [/bin, /data]
bpftrace                      0.27.0-2           Sandcastle-Common  [/bin, /data]  [root]
browser                       156.0-3            Sandcastle-Common  [/bin, /data]  [root, +64 dependencies]
   .....

The list command shows everything you chose to install. If you look closely, you'll see that there's some sets installed, as well as a specific /subpackage here. The next section will explain what those are, so read on.

Working with sets and subpackages

The Ur Project has implemented two concepts for making working with packages a little easier. These concepts help you to quicker install things, but also at a later stage, manage them, and even uninstall them, with a little less searching, listing, and enumerating them.

sets

Sets are package groups. They are displayed, and you would install them as shown in the above pkg list example: With the + character in front.

subpackages

Subpackages are all there is. There's no main concept of a package. Every package just consists of subpackages. For instance, the bash package has [/bin, /data, /info, /man, /doc, /dev, /debug, /debugsrc] as subpackages, and 40+ or so /lang/* ones.

This might sound complex, but it's not. What makes it easy is that pkg understands that if you just want bash that you're asking it to install bash/bin and bash/data. You can do that by doing a sudo pkg install bash/bin bash/data, but it's exactly the same as just doing sudo pkg install bash.

If you require a specific subpackage, you can say so. sudo pkg install bash/debug does exactly what you think it would - install the debug package for the bash program.

intent

The cool thing is that when you install bash, the pkg tool will remember that. And if you install a set like +network, it also is remembered. Why is this useful? It's because the installed packages are tracked by intent. If you install the +network set, and the set changes, then you get the new content of the new set automatically when you perform an upgrade.

In the same way, if you install bash and the dependencies of the bash package changed, you'd want those new dependencies installed as well. Everyone would consider it a bug if that didn't happen. So it works for both. And the pkg list output reflects what you chose to install, and not how it expanded to hundreds of subpackages.

configurable subpackage inclusion

You can choose to install bash/man automatically if you install bash. There is a documented configuration option in the pkg.toml(5) manual page. When using this option, you can automatically have things like sets install all the desired manual pages, /doc subpackages, or even /lang/pt_BR Brazilian Portuguese language packs for all packages on top of the default included subpackages.

Performing a roll back, and rolling forward again

A roll back is nothing more than an upgrade to a previous state. Updates are simple transactions, and with a known state, performing a rollback is just as easy.

Remember how we uninstalled luanti earlier on? Let's roll back to the point in time just before that. If you read back, you see that the pkg history for that example showed that it was recorded as number 7. We can therefore roll back to it by rolling back to number 6:

$ sudo pkg rollback --to 6
rolling back to the state after #6: 1085 subpackage(s), 0 to remove
Plan:
  install:
    + luanti         5.17.0-1  [/autostart, /bin, /data]
    + luanti/server  5.17.0-1
  fetch: 4 package(s), 8.6 MiB to download
Proceed? [y/N] y
fetched [1/4] luanti/autostart         2.9 KiB
fetched [2/4] luanti/data            727.4 KiB
fetched [3/4] luanti/bin               5.0 MiB
fetched [4/4] luanti/server            2.8 MiB
Transaction complete: 4 installed, 0 removed (#12, see `pkg history info 12`)
reclaimed 4 staged package(s), freed 8.6 MiB (--keep-staged to retain)
note: files are rolled back, system state is not -- triggers have run, and data a newer version migrated stays migrated

As you can see, the roll back was successful. There are some footnotes to keep in mind when performing a roll back:

  • As noted, triggers and other device management may have changed the system
  • You may have rolled back security updates
  • Running programs may need a restart, or they might even break.

And, finally

  • A roll back does not automatically lock your system from performing upgrades

You can pin packages. Theoretically you can sudo pkg pin every package installed to prevent updates. But the easiest way is to just not run the update, or pin certain packages that need to be held back.

For more information about the pkg tool and all the extra options available for these, and other sub commands, visit the Manual pages section.