What is this?

HitchHiker Linux is a general purpose Linux distribution that has been carefully assembled to give a more traditional, Unix-like experience. HitchHiker provides, out of the box, all development tools and libraries to rebuild itself from source code as well as being a solid base from which to create whatever system is desired.


man 42

HitchHiker Linux is a very Unix-like distribution of Linux with a focus on simplicity, elegance and providing a solid base that the end user can turn into whatever they see fit.

Core Principles:

  • The default installation should include the bare minimum required software to provide a solid base.
  • In itself, complexity is not bad. However, it must be justified, with a strong preference given to more robust and secure code over having every possible feature.
  • End users should not be discouraged from tinkering with their system.
  • The distribution should make as few assumptions as possible regarding end use.
  • While newer releases of software often eliminate bugs and vulnerabilities, newer software packages are not by default more secure than stable, mature packages (newer is not always better).
  • Any changes to the core system functionality, especially those which change expected functionality, must be well justified and well vetted before deployment.
  • The base installation should include everything required to rebuild itself from source.
  • The distribution should make as few changes to the upstream software as possible, delivering it as intended by the original author.
  • Patching of sources should only be done to fix bugs or vulnerabilities.
  • Power users and developers are users too, and the system should stay out of their way.

HHL was born of a desire to harness the greater hardware support of Linux while paying respect to the Unix systems from which Linux was born. The author was a long time user of FreeBSD who migrated to Arch for several years, but has become increasingly frustrated with Systemd, Gnome, RedHat and Ubuntu dominance. It is believed that there is a need for a distribution that does not pander to ease of use for casual users at the expense of putting up roadblocks for experienced Unix veterans.


HHL compiles for the following processor architectures:

  • x86
  • x86_64
  • armv7l
  • aarch64
  • riscv64

Of the above, HHL is known to boot and run well on x86_64 and aarch64. Running on other architectures will require more manual work on the part of the user in order to set up their boot loader.

Target Audience

My first computer was a Tandy TRS-80 handed down from an uncle. The interface consisted of a blinking cursor on a monochrome screen, and it had no storage beyond RAM and ROM. Whatever you could type into memory before shutting it off and run with the included Basic interpretor was the extent of the software that ran on that computer. As limited as it was, it was fascinating to me.

In this day and age an interface consisting of a blinking cursor without wallaper, icons, notifications and voice input is bewildering to the average human. Nevertheless, that is the interface that a fresh installation of HItchHiker will always present to the user. Therefore, it can be reasoned that the target audience will consist of individuals who either are comfortable with using a command line interface or are eager to learn. Some proficiency using Linux or Unix is helpful, but not 100% necessary given an ability and willingness to read the documentation and get used to being "close to the machine".

Indeed, HitchHiker will not do any kind of hand holding while you are installing and using your new system. You will be expected to learn the hows and whys of what makes a computer work. Most operating systems, including the majority of Linux distributions, will gladly install, configure, and run 100s of programs without your ever being aware that they are doing it. By the time you have achived proficiency with HitchHiker, you will know what every running process is for and why it is needed.

One major benefit of HitchHiker over other Linux systems is that the base installation contains a complete C/C++ development environment out of the box. The default packager, pkgsrc, delivers third party software as if you compiled it yourself from the source package. That is, it includes all documentation, shared and static libraries and development headers that come with the source distribution. Developers may find that HItchHiker is a great distribution in that it will stay out of their way.

Another benefit of HitchHiker is that it is small in comparison to other Linux distributions. It is much easier to build up a small system for an embedded device or a small Arm home server and fit the entire thing into a limited amount of storage.

What's Included

  • A full C and C++ development environment including compiler, headers and libraries.
  • Up to date versions of kernel, base libraries and toolchain components.
  • Where possible, BSD and historical Unix utilities have been incorporated.
  • Full documentation is included for all included software.
  • The HitchHiker build system is capable of bootstrapping itself from another Linux distro or from HitchHiker itself, and is available for x86, Arm and RiscV architectures.

What's Missing

  • Systemd - HitchHiker uses the S6 supervision suite and a minimal init.
  • No installer - HitchHiker is installed using Unix command line tools present on any Linux distribution.
  • No apt, rpm, dnf, pacman, etc. HitchHiker uses NetBSD Pkgsrc for installing extra software.
  • No daemons beyond what is required to provide a functional command prompt are started by default.
  • No extra configuration is done to provide a "consistent look and feel" or any such crap. The Linux world is full of choices. Unfortunately, among the hundreds of installable offerings the vast majority are "vanity distros" which are just a remix of another distribution, with a different set of installed packages and a few cool wallpapers.

HitchHiker on the other hand is not based on any other distribution of Linux. It is a fully independent offering which tracks the most recent releases of the Linux kernel, Glibc, GCC etc. It's smaller userland utilities have been mostly ported from BSD or implemented from scratch. It's source tree can compile the entire operating system with a single command using Makefiles. We strive for an active and independent presence and want to push open source into new and exciting frontiers, such as RiscV, while paying homage to classic Unix. While there are other offerings that cover some of the same territory (Arch, Gentoo) we felt that there was space for something different.



Downloading Hitch Hiker Linux binary tarballs


The x86 platform includes all 32-bit Intel and Intel compatible processors ranging from i386 to i786 processors. For the purposes of installation, the x86_64 architecture, including all AMD64 and Intel 64-bit processors, is identical in function and included in this page.


Please note that the minimum supported processor is i486. This is not a limitation specific to HitchHiker, but a limitation of the Linux Kernel itself and Glibc. Should you have a computer of this vintage, and wish to get it running, you have the choice of installing an older and likely unsupported distribution, or installing an operating system descended from 4.4BSD (FreeBSD, NetBSD, and OpenBSD).

It is necessary to create and format partitions in advance for HitchHiker. There are various tools available for creating partitions on Linux. While graphical tools are available, it is recommended to use one of fdisk, cfdisk or Gnu parted to create partitions. All three are reliable and well maintained, as well as being much simpler to use than one might expect. The graphical tools such as Gparted often suffer from a lack of maintenance.

Partition layout is left mostly to the user, but it is recommended to have a separate partition for /home and one for /boot (particularly if booting from EFI rather than legacy Bios). The default kernel that ships with the binary sets for HItchHiker uses the same config as Slackware's huge_s kernel and has good filesystem support, but it is still recommended that for the root partition be on an ext4 filesystem.

Creating partitions

Extracting the binaries

Creating the root password

Setting up the Bootloader


Raspberry Pi





The Build Process

This section describes the steps that the HitchHiker build tree takes when building itself from source. Note that this is not a list of the commands that must be run by the user, those are actually quite simple. Rather, this page is here because it is both useful and reasshuring to understand what is being done when one does run the commands.

It is expected that certain programs are available on the host system, ie the system that HitchHiker is being built on. In the case that certain programs do not exist, those programs are compiled in the 'bootstrap' portion of the build. HitchHiker puposely keeps this part light and prefers to use the native tools of the host.

In the second half of the bootstrap phase, a sysroot compiler and linker is built and installed under /toolchain. This toolchain may or may not be a cross toolchain, but in either case is of the same version of gcc and binutils as are to be used in the finished system and are built in such a way that they search for headers and libraries under /src/build rather than /.

In the case that we are compiling for an architecture that is different than the one which is being used to build the system, this toolchain is what is known as a cross toolchain. What this means is that the compiler and linker run on our build machine (the machine performing the build) but produce machine code that runs on our host machine (the machine the finished system will in fact run on).

The actual build of the sysroot compiler takes place in several steps:

  1. The binutils package, which contains our linker and assembler.
  2. A temporary and minimally capable gcc compiler is built, which is only capable of building our C library.
  3. The linux kernel headers are installed into our sysroot.
  4. The temporary gcc and binutils built in step 1 are used to build glibc, which is installed into our sysroot.
  5. The final sysroot gcc compiler is built, which is a fully capable C and C++ compiler for our final system.

We then use the toolchain and bootstrap tools that we have built to compile the rest of the final system and install it into our sysroot.

Downloading the Hitch Hiker Linux source

The Hitch Hiker Linux source code is available as an xz compressed tarball from the website, or can alternatively be cloned from the main git repository.

The current stable source tarball can be fetched using wget:

wget -c
tar -xJf src.tar.xz

Alternatively, should one wish to build the most recent development version of HitchHiker, the source can be checked out via git over https.

git clone


Currently, the build tree expects to be located in the top level directory /src, and it is therefore necessary to either cd / prior to running the previous commands, or else to bind mount the actual source directory onto /src prior to building. This requirement may be changed in the future in order to increase flexibility.

Preparing to Build

If Hitch Hiker is being built on a Linux system other than itself, the following software is expected to be present:

  • Binutils - version 2.25 or greater
  • Bison - version 2.7 or greater
  • a functional bzip2 and bunzip2 command
  • a functional diff command
  • a functional find command
  • Gcc - version 6.2 or greater
  • a functional grep command
  • a functional gzip and gunzip command
  • Linux kernel version 3.2 or greater
  • M4 - version 1.4.10 or greater
  • GNU make
  • a functional patch command
  • GNU sed is required to build the Linux kernel
  • a functional tar command
  • Texinfo - version 4.7 or greater
  • a functional xz and unxz command Change directory to /src and create your file by copying and editing it appropriately. The comments in the sample explain what each variable does.
cd /src

As a final step before building, it is neccessary to prepare the environment in which we are going to build Hitch Hiker. There is a script provided for this purpose which cleans up some environment variables and sets one MAKEFLAG in order to let make find our include files.

source scripts/

Building HitchHiker

Post Install Configuration

This section describes the steps which should be taken to configure a freshly installed system on first boot.

Setting the root password

Setting the timezone

HitchHiker will default to Eastern Standard Time in the United States. If this is incorrect for where you reside, create the file /etc/tz and edit it's contents to set the variable TZ to point to the correct timezone. You can determine what the correct timezone should be by running the command tzselect.

Let's give as an example someone living in Stockholm, Sweden.

Please identify a location so that time zone rules can be set correctly.
Please select a continent, ocean, "coord", or "TZ".
1) Africa							     7) Australia
2) Americas							     8) Europe
3) Antarctica							     9) Indian Ocean
4) Arctic Ocean							    10) Pacific Ocean
5) Asia								    11) coord - I want to use geographical coordinates.
6) Atlantic Ocean						    12) TZ - I want to specify the timezone using the Posix TZ format.
#? 8
Please select a country whose clocks agree with yours.
1) Åland Islands	   9) Bulgaria		    17) Germany		      25) Jersey		33) Montenegro		  41) San Marino	    49) Ukraine
2) Albania		  10) Croatia		    18) Gibraltar	      26) Latvia		34) Netherlands		  42) Serbia		    50) Vatican City
3) Andorra		  11) Cyprus		    19) Greece		      27) Liechtenstein		35) North Macedonia	  43) Slovakia
4) Austria		  12) Czech Republic	    20) Guernsey	      28) Lithuania		36) Norway		  44) Slovenia
5) Belarus		  13) Denmark		    21) Hungary		      29) Luxembourg		37) Poland		  45) Spain
6) Belgium		  14) Estonia		    22) Ireland		      30) Malta			38) Portugal		  46) Sweden
7) Bosnia & Herzegovina	  15) Finland		    23) Isle of Man	      31) Moldova		39) Romania		  47) Switzerland
8) Britain (UK)		  16) France		    24) Italy		      32) Monaco		40) Russia		  48) Turkey
#? 46

The following information has been given:

	Germany (most areas), Scandinavia

Therefore TZ='Europe/Berlin' will be used.
Selected time is now:	Tue Sep  6 17:46:11 CEST 2022.
Universal Time is now:	Tue Sep  6 15:46:11 UTC 2022.
Is the above information OK?
1) Yes
2) No
#? 1

You can make this change permanent for yourself by appending the line
	TZ='Europe/Berlin'; export TZ
to the file '.profile' in your home directory; then log out and log in again.

Here is that TZ value again, this time on standard output so that you
can use the /usr/bin/tzselect command in shell scripts:

This user would then create the file /etc/tz with the following contents.


Setting the hostname

The hostname is set during the boot process to the contents of the file /etc/hostname. Edit this file with either vi or ee. The hostname takes the form of hostname.domain, where the domain is entirely optional.

Editing this file will cause the hostname to be set correctly on the next boot (and subsequently thereafter). However, it will not take effect until after reboot. In order to set the hostname now, use the hostname command with your desired hostname as it's argument.

# Example - set the hostname to

Adding a User Account

It is bad practice to log in as the root user on any Unix-like system for anything other than performing system administration tasks. You will want to create a user account for yourself as soon as possible. This is done using the useradd command. We're goind to give an example here. However, it is good to familiarize yourself with the various flags and arguments by looking up and reading the man page using the command man useradd.

It is quite likely that you will not get everything exactly correct the first time. It is also likely that at some future time you may wish to edit some characteristic of the created user, such as supplementary groups to which this user belongs.

While we're on the subject of supplmentary groups, it is a good idea to make your own user account a member of the wheel group, allowing you to su to the root user account.

Our example

Our example user is Ford Prefect.

useradd -G wheel -m -s /bin/zsh -c "Ford Prefect" ford
passwd ford

Setting up Networking

The first step in setting up our network is to determine the name of the network device that we are going to connect with. We're goind to start by running the ip command to list our interfaces, and then once that is done we can move on to setting up our connection in one of the following subsections for wired or wireless as appropriate.

ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
    link/ether dc:a6:32:2a:97:94 brd ff:ff:ff:ff:ff:ff
3: wlan0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN mode DORMANT group default qlen 1000
    link/ether ca:d0:a4:6c:cf:5d brd ff:ff:ff:ff:ff:ff permaddr dc:a6:32:2a:97:95

The results for 1: lo ... represent the loopback interface. We also see an ethernet device eth0 and a wireless device wlan0. To configure the ethernet interface eth0 go ahead to the section wired. If instead you intend to use the wireless interface wlan0 proceeed to section wireless.

Wired Connection

A wired ethernet connection is the simplest to set up. All that is required is to give the interface an ip address and routing. This can be done statically or via dhcp. After getting the connection working, we'll create an s6-rc service definition so that on every boot the network will be properly configured at boot time.

Bringing the interface Up

The first step in setting up any network interface is making sure that the interface is up. This is an example of the output of ip link show for an interface which is down.

2: eno1: <BROADCAST,MULTICAST> mtu 1500 qdisc fq_codel state DOWN mode DEFAULT group default qlen 1000

To power on this device we need to bring it up with the following command, replacing eno1 with the name of your actual device.

ip link set eno1 up

We then verify that the device is in fact up by running ip link show again and checking that the device is UP.

% ip link show eno1
2: eno1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN mode DEFAULT group default qlen 1000


Getting a dynamic ip using dhcpcd

HitchHiker comes with the dhcpcd client for dynamic network configuration. This is the quickest way to configure a network interface.

# Get a dynamic ip address for the eth0 interface
dhcpcd eth0

Setting a static ip

A Static ip address can be configured by once again using the ip command, this time with it's address subcommand. We're going to use CIDR Notation here to also set a correct network prefix and broadcast. Most users will have a subnet mask of, with 24 leading 1-bits. Don't worry if some of this is beyond your understanding, the commands should work even if you don't understand every aspect.

# Set the ip address to
ip address add broadcast + dev eth0

After setting the ip address, we next need to set up a route for this device to reach the rest of the network. This is done once again with the ip command, this time using the route subcommand.

# Route goes through our router which has the internal ip
ip route add default via eth0

There is one more step to configuring a network interface manually. If we configure a dynamic address via dhcpcd, the client also configures domain name resolution for us. When you configure an interface manually this is something that you must do yourself. Edit the file /etc/resolv.conf to set a primary and a secondary dns resolver. You can use the Google dns resolvers at and or, if you prefer, there is a list of public DNS servers at

# /etc/resolv.conf

Wireless Connection

There are a few extra steps which must be performed in order to set up a wireless network connection. While there are a number of gui tools designed to manage the connection with a point and click interface, the wpa_supplicant tool is often what is invoked as the backend for such tools. It is both simple to set up manually and more reliable than most other tools. Most importantly, it comes as part of the HitchHiker Linux base install.

Note: It is perfectly possible to set up a wireless association using the iwconfig program rather than wpa_supplicant, and this will have the advantage of not requiring another daemon to run. Since wireless connections are often used in the context of a roaming setup, ie a laptop which will be carried from place to place and connected to various networks, wpa_supplicant is usually preferred. However if you have a device which will never roam yet cannot connect via a wired interface, the manual page for iwconfig gives instructions for associating a wireless network this way.

The first step in connecting is exactly as for a wired connection, setting the interface state to UP. For instructions refer back to the wired subchapter.

Creating the service definition

Managing Processes

Installing Third Party Software

Hitch Hiker uses the pkgsrc framework for installing extra software on top of the base system. Contrary to what is common in the world of Linux, there is a clear distinction between the base system and all third party packages. This, in turn, allows for more developer focus on the base system and less time packaging software. This is the model followed by all of the various BSD systems, where the base system and packages are considered to be separate projects.

What is Pkgsrc

Pkgsrc is a cross platform framework for packaging and installing third party software which is developed and maintained by the NetBSD project. Currently it works on all BSD systems, Minix, Darwin,MacOS X, and Linux to name a few, across multiple architectures.

Further Reading

In addition to this chapter you are highly encouraged to read The pkgsrc guide and keep it handy as reference, as a full reference to pkgsrc is beyond the scope of this chapter.

Getting Pkgsrc

The current stable pkgsrc can be downloaded from this link. It should then be extracted to /usr/pkgsrc.

wget -c
tar -xjf pkgsrc.tar.bz2 -C /usr

Bootstrapping Pkgsrc

Before installing packages from source or from binary, it is necessary to bootstrap pkgsrc. This is neccessary in order to build the tools that pkgsrc requires which are not a part of the Hitch Hiker base system.

cd /usr/pkgsrc/bootstrap

Once this is done it is necessary to either reload the shell startup files or log out and back in again, in order to add /usr/pkg/bin and /usr/pkg/sbin to our $PATH.

exec zsh --login

As a final step, it is neccessary to add /usr/pkg/lib to the default linker path. This path is configured in /etc/ and can be extended with files placed in /etc/ Finally, after configuring the linker paths, we run ldconfig to update the linker's cache of shared libraries.

install -d /etc/
echo '/usr/pkg/lib' > /etc/


Ordinarily the preceding command would be run as the root user. It is, however, possible to install packages as an unprivileged user by first making the package prefix directory writable by that user. In the case of a normal installation this would entail creating /usr/pkg and transferring ownership of it using the chown command before bootstrapping pkgsrc. It is also possible to bootstrap pkgsrc in one's own home directory. However, as this will break compatability with any provided binary packages it is therefore discouraged.

Installing Binary Packages

It is entirely possible to skip this step if one wishes to build all software from source. However, should one wish to work with binary packages provided by Hitch Hiker, it is recommended that the first package built be the pkgin package manager.

zaphod@magrathea% cd /usr/pkgsrc/pkgtools/pkgin
zaphod@magrathea% bmake install clean clean-depends

To configure pkgin, edit the file /usr/pkg/etc/pkgin/repositories.conf to point towards the package repository appropriate for your architecture and version of Hitch Hiker. The server is structures as follows:

└── 2021q2              # Release version
    ├── src             # Source tree
    ├── aarch64         # Architecture
    │   ├── packages
    │   │   └── All     # Package repository
    │   ├── release     # Release tarballs

Therefore, if the Hitch Hiker release was 2021q2 and the architecture of your machine was riscv64, the repository can be added with the following command:

zaphod@magrathea% echo '' \
  >> /usr/pkg/etc/pkgin/repositories.conf

Once pkgin is installed and configured it functions similarly to any good package manager one might have previously used under Linux, such as apt or pacman. To see the list of possible operations just run the pkgin command without arguments:

zaphod@magrathea% pkgin
Usage: pkgin [-cdfhlnPtvVy] command [package ...]

Commands and shortcuts:
list                (ls  ) - List installed local packages
avail               (av  ) - List all available remote packages
search              (se  ) - Search for a remote package
install             (in  ) - Install or upgrade packages
update              (up  ) - Refresh local and remote package lists
upgrade             (ug  ) - Upgrade all packages
full-upgrade        (fug ) - Upgrade all packages (deprecated)
remove              (rm  ) - Remove packages and any dependent packages
keep                (ke  ) - Mark packages that should be kept
unkeep              (uk  ) - Mark packages that can be autoremoved
export              (ex  ) - Display PKGPATH for all keep packages
import              (im  ) - Import keep package list from file
show-keep           (sk  ) - Display keep packages
show-no-keep        (snk ) - Display autoremovable packages
autoremove          (ar  ) - Remove orphaned dependencies
clean               (cl  ) - Remove downloaded package files
show-deps           (sd  ) - List remote package direct dependencies
show-full-deps      (sfd ) - List remote package full dependencies
show-rev-deps       (srd ) - List local package reverse dependencies
provides            (prov) - Show which shared libraries a package provides
requires            (req ) - Show which shared libraries a package requires
show-category       (sc  ) - List all packages belonging to a category
show-pkg-category   (spc ) - Show categories a package belongs to
show-all-categories (sac ) - List all known categories
pkg-content         (pc  ) - Show remote package content
pkg-descr           (pd  ) - Show remote package long-description
pkg-build-defs      (pbd ) - Show remote package build definitions
stats               (st  ) - Show local and remote package statistics

Building Source Packages

The first step in building a package is to locate the directory within the pkgsrc tree that contains that package, and then entering that directory. There is a provided search utility called pkglocate which can be used to do a keyword search. However, in practice pkglocate is not a very effective search tool.

A much better search tool can be found at pkgtools/pkgfind. To install it:

cd /usr/pkgsrc/pkgtools/pkgfind
bmake install clean clean-depends

Now running pkgfind <searchterm> should return a much better list of search results.


It is good practice to always run the clean and clean-depends targets after running bmake install, to avoid leaving old work directories all over the tree As demonstrated by our installation of pkgfind, the general procedure to build a package using pkgsrc is to:

  1. Locate the directory containing the package we wish to install.
  2. cd into that directory
  3. Run bmake install in that directory.


We run bmake as opposed to just make because pkgsrc uses the NetBSD version of the make utility, which supports somewhat different Makefile syntax than GNU make.

Extending Pkgsrc

While pkgsrc contains an extensive collection of software out of the box, there are times when there are packages that have not yet been packaged or have build failures on Hitch Hiker. For those feeling somewhat adventurous, here are two ways to extend the available packages, providing software not in the default distribution or alternative packages with Hitch Hiker specific bug fixes.


The pkgsrc-wip project is a collection of work in progress packages which for one reason or another have not yet been accepted into the main distribution. Much of the time these packages are perfectly functional, but might not work on every OS that pkgsrc supports. The pkgsrc-wip repository is managed via git, and due to the main pkgsrc framework being managed under CVS it is safe to clone pkgsrc-wip right into pkgsrc.

cd /usr/pkgsrc
git clone wip

This will put all of pkgsrc-wip right inside pkgsrc at /usr/pkgsrc/wip. Once there, using wip is exactly the same as using the rest of pkgsrc.


The pkgsrc-hhl project is and extension to pkgsrc containing packages that are intended specifically for Hitch Hiker. These packages may add functionality not available in pkgsrc, fix build issues, or integrate packages from pkgsrc better with Hitch Hiker. Installation and usage of pkgsrc-hhl is similar to pkgsrc-wip.

cd /usr/pkgsrc
git clone hhl

Updating HitchHiker Linux

From Binary Sets

From Source