From b13d38fddf473efc4a06c11112ee35432cc4334b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Rolim?= Date: Mon, 6 Apr 2020 01:42:28 -0300 Subject: [PATCH 1/2] Usage: remove usage pages and link to docs instead The documentation regarding these tools should be centralized in the docs. --- index.html | 4 +- usage/runit/index.markdown | 185 -------------------- usage/xbps/index.markdown | 346 ------------------------------------- 3 files changed, 2 insertions(+), 533 deletions(-) delete mode 100644 usage/runit/index.markdown delete mode 100644 usage/xbps/index.markdown diff --git a/index.html b/index.html index 7e2f7cf..f5ccd63 100644 --- a/index.html +++ b/index.html @@ -44,7 +44,7 @@

Rolling release

runit

We use runit as the init system and service supervisor.

-

runit is a simple and effective approach to initialize the system with reliable service supervision. See the usage page for a brief introduction.

+

runit is a simple and effective approach to initialize the system with reliable service supervision. See the documentation page for a brief introduction.

@@ -56,7 +56,7 @@

LibreSSL

xbps

xbps is the native system package manager, written from scratch with a 2-clause BSD license.

-

xbps allows you to quickly install/update/remove software in your system and features detection of incompatible shared libraries and dependencies while updating or removing packages (among others). See the usage page for a brief introduction.

+

xbps allows you to quickly install/update/remove software in your system and features detection of incompatible shared libraries and dependencies while updating or removing packages (among others). See the documentation page for a brief introduction.

xbps-src

diff --git a/usage/runit/index.markdown b/usage/runit/index.markdown deleted file mode 100644 index 592d034..0000000 --- a/usage/runit/index.markdown +++ /dev/null @@ -1,185 +0,0 @@ ---- -layout: std -title: Enter the void - runit ---- -* TOC -{:toc} - -# Overview - -runit is a suite of tools which include a PID 1 init as well as a -daemontools-compatible process supervision framework, along with utilities -which streamline creation and maintenance of services. - -## Example Process Tree - -Example of a basic running system with runit as PID 1 - -~~~ -# pstree -a -runit - `-runsvdir -P /run/runit/runsvdir/current... - |-runsv dhcpcd-eth0 - | `-dhcpcd -B eth0 - |-runsv sshd - | `-sshd -D - |-runsv agetty-tty1 - | `-agetty --noclear tty1 38400 linux - |-runsv agetty-tty2 - | `-agetty tty2 38400 linux - |-runsv agetty-tty3 - | `-agetty tty3 38400 linux - |-runsv agetty-tty4 - | `-agetty tty4 38400 linux - |-runsv agetty-tty5 - | `-agetty tty5 38400 linux - |-runsv agetty-tty6 - | `-agetty tty6 38400 linux - `-runsv udevd - `-udevd -~~~ - -Note how each service is managed by its own runsv process, further explanation below. - -## Framework - -runit employs a concept of a service directory, responsible for an individual service, -which is a process to monitor and an optional log service. - -### void runit directories - -- `/var/service` - always linked to the currently active runlevel -- `/etc/sv` - directory containing service files placed by xbps -- `/etc/runit/runsvdir` - directory containing all available runlevels - -### Service Directory layout - -A service directory requires only one file, an executable named `run` which is expected -to exec a process in the foreground. If the service directory contains a directory named -`log`, a pipe will be opened from the output of the `run` process in the service directory -to the input of the `run` process in the `log` directory. - -The `sshd(8)` run service: - - -~~~ -#!/bin/sh -ssh-keygen -A >/dev/null 2>&1 # Will generate host keys if they don't already exist -[ -r conf ] && . ./conf -exec /usr/sbin/sshd -D $OPTS 2>&1 -~~~ - -will run the sshd process in the foreground, making sure all output (stderr, stdout) are directed -to stdout, which will be piped to the log below (`/etc/sv/sshd/log/run`): - -~~~ -#!/bin/sh -[ -d /var/log/sshd ] || mkdir -p /var/log/sshd -exec chpst -u root:adm svlogd -t /var/log/sshd -~~~ - -### User Commands - -- `chpst(8)` - runit process environment manipulator -- `sv(8)` - runit utility to manage and inspect services -- `svlogd(8)` - runit logging utility -- `runsvchdir(8)` - runit "runlevel" switcher - -### System Commands - -- `runit(8)` - a UNIX process number 1 -- `runsvdir(8)` - starts and monitors a collection of runsv(8) processes -- `runsv(8)` - starts and monitors a service and optionally an appendant log service - - -## Examples - -System services require root access for most of these operations. Use `sudo(8)` with these -commands as a normal user for the desired system-level behavior. - -### Service Status - -To see the status of a supervised service use `sv s ` - -for example, - - # sv s sshd - -returns - - run: sshd: (pid 42) 1587s - -To see the status of all services, use `sv s /var/service/*`. - -### Stop/Start/Restart - -Start a service - - # sv u sshd - -Stop a service - - # sv d sshd - -Restart a service - - # sv t sshd - -Each of these is a shortcut, for 'up', 'down', and 'terminate', respectively. Only the first letter -of each word is recognized (see `sv(8)`). - -More verbose forms of the above - - # sv start sshd - # sv stop sshd - # sv restart sshd - -Each of these will also return the status of the service upon exit. - -### Enabling a service - -void-provided service directories live in `/etc/sv`. To enable a service in the current runlevel, -create a symlink from it to `/var/service`. - - # ln -s /etc/sv/sshd /var/service/ - -Once a service is linked it will always start on boot and restart if it stops (unless administratively downed). - -### Disabling a service - -To disable a service in the current runlevel remove the symlink to its service directory from `/var/service`. - - # rm /var/service/sshd - -Removing the symlink will also stop the service. - -## Run Levels - -runit supports an unlimited amount of run levels, implemented as directories located under `/etc/runit/runsvdir/`. - -The default runlevels shipped with void are `default` and `single`: - -- The `single` runlevel is meant to be used as `rescue` or `single user` target and it will only start `sulogin(8)` -by default. -- The `default` runlevel will start `agetty(8)` and some more services; it's the `multi-user` target by default. - -In order to create a new runlevel, it is best to start by copying this `default` and removing/adding -symlinks to service directories to create the runlevel you desire. - - # cp -a /etc/runit/runsvdir/default /etc/runit/runsvdir/my_runlevel - # rm /etc/runit/runsvdir/my_runlevel/agetty-tty[3456] # remove all gettys except for tty1 and tty2 - # ln -s /etc/sv/dcron /etc/runit/runsvdir/my_runlevel/ # add the cron service - -To change the runlevel use the `runsvchdir(8)` command: - - # runsvchdir my_runlevel - -To make this runlevel the default runlevel, append it to your bootloader's kernel command line. - -For GRUB edit `/etc/default/grub`, adding: - - GRUB_CMDLINE_LINUX_DEFAULT="loglevel=4 my_runlevel" - -and rebuild the grub configuration file (`update-grub`) - -Now your default runlevel will be `my_runlevel`. diff --git a/usage/xbps/index.markdown b/usage/xbps/index.markdown deleted file mode 100644 index 4707ac0..0000000 --- a/usage/xbps/index.markdown +++ /dev/null @@ -1,346 +0,0 @@ ---- -layout: std -title: Enter the void - xbps ---- - -* TOC -{:toc} - -# Introduction - -xbps contains some utilities to accomplish a certain task for package management -(additional utilities not listed here were omitted for simplicity): - -- `xbps-install(1)` - XBPS utility to (re)install and update packages -- `xbps-query(1)` - XBPS utility to query for package and repository information -- `xbps-remove(1)` - XBPS utility to remove packages -- `xbps-reconfigure(1)` - XBPS utility to configure installed packages -- `xbps-pkgdb(1)` - XBPS utility to report/fix issues and modify the package database (pkgdb) -- `xbps-rindex(1)` - XBPS utility to manage local binary package repositories -- `xbps-alternatives(1)` - XBPS utility to handle alternatives - -This page shows brief examples for common usage, refer to the manual pages for more information. - -### Repositories - -Repositories are the heart of the `xbps` package system. Repositories can be *locally* or *remotely* -available: - -- *local*: repository is available in a local directory, e.g `/xbps/repository`. -- *remote*: repository is available in a remote location, e.g `http://my.domain.com/repository`. - -Repositories can be declared in a file stored in `/etc/xbps.d` with a simple format: - - repository= - -Where `url` can be a path to a directory (local) or an URL to the repository (remote): - - # echo 'repository=/path/to/dir' > /etc/xbps.d/my-local-repo.conf - # echo 'repository=http://my.domain.com/repository' > /etc/xbps.d/my-remote-repo.conf - -System repositories can be available at `/usr/share/xbps.d`, files bearing the same filename -available in `/etc/xbps.d` override those defined in `/usr/share/xbps.d`. - -#### Official Repositories - -- http://alpha.de.repo.voidlinux.org (EU: Germany *default*) -- http://beta.de.repo.voidlinux.org (EU: Germany) -- http://alpha.us.repo.voidlinux.org (USA: Kansas City) -- http://mirror.clarkson.edu/voidlinux/ (USA: New York) -- http://mirrors.servercentral.com/voidlinux/ (USA: Chicago) - -You can find more about mirrors in the [Download page](https://voidlinux.org/download/#mirrors). - -The official repositories (glibc) are signed with the following RSA key: - - Signed-by: Void Linux - 4096 60:ae:0c:d6:f0:95:17:80:bc:93:46:7a:89:af:a3:2d - -You can print the `repository` RSA public key fingerprint with `xbps-query`: - - $ xbps-query -vL - -#### Official Repositories (musl) - -Musl repositories are in the /current/musl directory of the [mirrors](https://voidlinux.org/download/#mirrors), e.g. -- http://alpha.de.repo.voidlinux.org/current/musl/ (EU: Germany) - - -The musl repositories are signed with the following RSA key: - - Signed-by: Void Linux - 4096 3d:b9:c0:50:41:a7:68:4c:2e:2c:a9:a2:5a:04:b7:3f - -You can print the `repository` RSA public key fingerprint with `xbps-query`: - - $ xbps-query -vL - -#### Subrepositories - -Additional sub repositories exist in the official repositories: - -- debug (contains -dbg pkgs for debugging) -- nonfree (contains pkgs that don't have free licenses) -- multilib (contains 32bit pkgs for 64bit platforms) -- multilib/nonfree (contains non free 32bit pkgs for 64bit platforms) - -Packages for these repositories exist in the `main` repository, i.e: - - $ xbps-query -Rs void-repo - [*] void-repo-debug-5_1 Void Linux drop-in file for the debug repository - [*] void-repo-multilib-5_1 Void Linux drop-in file for the multilib repository - [*] void-repo-multilib-nonfree-5_1 Void Linux drop-in file for the multilib/nonfree repository - [*] void-repo-nonfree-5_1 Void Linux drop-in file for the nonfree repository - -After installing any of them don't forget to synchronize the repository data: - - # xbps-install -S - -### Download static binaries - -Static binaries for Linux built with the *musl C library* are available at: - -- [aarch64](http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.aarch64-musl.tar.xz) -- [armv6hf](http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.armv6l-musl.tar.xz) -- [i686](http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.i686-musl.tar.xz) -- [x86\_64](http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.x86_64-musl.tar.xz) -- [mipsel32](http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.mipsel-musl.tar.xz) -- [mips32](http://alpha.de.repo.voidlinux.org/static/xbps-static-latest.mips-musl.tar.xz) - -### xbps-install(1) - -This utility can be used to install, update, reinstall, or downgrade a package, -or all packages in your system, and to syncronize the remote repositories data. - -#### Synchronize remote repository data - - # xbps-install -S - -Remote repositories in xbps contain an archive that stores metadata of all -available packages in that repository. This data must be up-to-date. The `-S` flag -can be used with other mode to always sync. - -#### Installing/updating a single package - - # xbps-install -S pkg - -If `pkg` is installed and there's a newer version, the package will be upgraded to -that version of the first repository containing it; otherwise the package will be installed. - -#### Reinstalling/downgrading to a specific package version - - # xbps-install -Sf pkg-1.0_1 - -By specifying a specific package version and the `-f` flag, the package will be reinstalled -or downgraded to that version if the package is currently installed. - -#### Updating your system - - # xbps-install -Su - -This will update all currently installed packages to the latest version found in the -registered repositories, performing a global system update. This is the recommended command -to keep your system up to date daily. - -### xbps-query(1) - -This utility can be used to query for information about packages installed in your system -and in specific repositories. - -The `xbps-query(1)` has two working modes: - -- **Local**: shows information of packages installed in the rootdir -- **Repository**: shows information of packages stored in repositories - -The `-R` or `--repository` option switches to the `repository` mode. Most options are able -to work in `local` and `repository` mode. - -#### Listing registered repositories - - $ xbps-query -L - -#### Listing installed packages - - $ xbps-query -l - -#### Showing information for a package - - $ xbps-query [-R] pkg - -#### Showing the files list for a package - - $ xbps-query [-R] -f pkg - -#### Showing the required dependencies for a package - - $ xbps-query [-R] -x pkg - -#### Showing the reverse dependencies for a package (packages that depend on it): - - $ xbps-query [-R] -X pkg - -#### Searching for packages matching its package name/version and/or description - - $ xbps-query [-R] -s pattern - -#### Searching for packages matching a filename - - $ xbps-query [-R] -o "*/filename" - -### xbps-remove(1) - -This utility can be used to remove installed packages and clean the cache directory. - -#### Removing a single package - - # xbps-remove pkg - -#### Removing a single package and recursively all packages that were installed as dependencies - - # xbps-remove -R pkg - -#### Cleaning up the cache directory - - # xbps-remove -O - -#### Removing all package orphans - - # xbps-remove -o - -#### Removing all package orphans and clean the cache directory - - # xbps-remove -Oo - -### xbps-reconfigure(1) - -This utility can be used to configure or force reconfiguration of an installed package. - -When `xbps-install(1)` installs a package, it performs the task in two phases: *unpacking* and *configuration*. -The *unpacking* phase unpacks the package files of the binary package into disk, and the *configuration* -phase performs additional steps necessary to execute the software. - -Packages that were not configured can be listed with `xbps-query -l` if its first two characters -are `uu`. In that case, those packages should be `reconfigured`: - - # xbps-reconfigure -a - -#### Configure a package that is in *unpacked* state - - # xbps-reconfigure pkg - -#### Configure all packages that are in *unpacked* state - - # xbps-reconfigure -a - -#### Force reconfiguration of a package (even if it was configured previously): - - # xbps-reconfigure -f pkg - - -### xbps-pkgdb(1) - -This utility can be used to report errors in installed packages, as well as changing some of its -properties. - -#### Checking for errors in an installed package - - # xbps-pkgdb pkg - -If `pkg` does not have any error there won't be any output and return value will be 0. - -#### Checking for errors in all installed packages - - # xbps-pkgdb -a - -#### Changing properties of an installed package - -An installed package can have different modes depending how it was installed. If a package -was *explicitly* installed by the administrator and not as a *dependency*, its **installation** mode -will be set to **manual**, otherwise **auto**. - -Packages that were installed manually can be listed with: - - $ xbps-query -m - -or per-package: - - $ xbps-query -p automatic-install pkg - -It's possible to change this mode with `xbps-pkgdb(1)`: - - # xbps-pkgdb -m auto pkg - # xbps-pkgdb -m manual pkg - -A package can also be put *on hold* mode to skip updates while performing a system update: - - # xbps-pkgdb -m hold pkg - # xbps-pkgdb -m unhold pkg - -A package can also be put in *repository locked mode* and will only be possible to update it -if there's an update in the same *repository* that was used for installing: - - # xbps-pkgdb -m repolock pkg - # xbps-pkgdb -m repounlock pkg - -### xbps-rindex(1) - -This utility can be used to generate local repositories, remove obsolete binary packages stored -in them, and to sign the packages with a cryptographic key. - -#### Creating a local repository - - $ xbps-rindex -a /path/to/dir/*.xbps - -Once the command has run, a local repository is available at `/path/to/dir` and can be used as an argument -to the `--repository` option or be declared in `/etc/xbps.d/`. - -#### Adding a specific package to a repository - - $ xbps-rindex -a /path/to/dir/foo-1.0_1.x86_64.xbps - - -#### Force addition of a specific package to a repository - - $ xbps-rindex -f -a /path/to/dir/foo-1.0_1.x86_64.xbps - -#### Cleaning a repository (removing stalled entries) - - $ xbps-rindex -c /path/to/dir - -#### Removing obsolete packages in a repository - - $ xbps-rindex -r /path/to/dir - -#### Signing a repository - -Initialize the repository metadata with signing properties: - - $ xbps-rindex --sign --signedby "I'm Groot" /path/to/dir - -Signs all binary packages stored in repository with your specified RSA key. -If the `--privkey` argument not set, it defaults to `~/.ssh/id_rsa`. - - $ xbps-rindex --signedby "I'm Groot" --sign-pkg /path/to/dir/*.xbps - -### xbps-alternatives(1) - -The `xbps-alternatives` utility lists or sets the alternatives provided by -installed packages. Alternatives are classified by groups, and a group -contains a number of symbolic links which are applied when the group is -set. - -#### List all alternatives - - $ xbps-alternatives -l - -#### List alternatives for a specific package - - $ xbps-alternatives -l foo - -#### Set all alternative groups - - $ xbps-alternatives -s foo - -#### Set specific alternative groups - - $ xbps-alternatives -g bar -s foo From 86d574ff3c16a766aaf2c0ff94d93b13d793503a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Rolim?= Date: Mon, 6 Apr 2020 01:43:31 -0300 Subject: [PATCH 2/2] FAQ: remove unlinked pages --- faq/index.markdown | 731 --------------------------------------------- 1 file changed, 731 deletions(-) delete mode 100644 faq/index.markdown diff --git a/faq/index.markdown b/faq/index.markdown deleted file mode 100644 index 5a7f076..0000000 --- a/faq/index.markdown +++ /dev/null @@ -1,731 +0,0 @@ ---- -layout: std -title: Enter the void - FAQ ---- -* TOC -{:toc} - -# Introduction - -# Installation - -Void Linux provides a dialog based installation script, which can be used for most basic setups. -The script however does not work for slightly more specific setups, in this case you should use the manual installation method. - -The following features are **not** supported by the installation script: - -* LVM -* Luks -* ZFS - -You can either install Void Linux from one of the live images using one of both installation methods or use another linux distribution and the manual installation method with static [xbps](/usage/xbps) binaries. - -## Downloading - -### Live Images - -### Static XBPS binaries - -Static xbps images can be downloaded from [https://alpha.de.repo.voidlinux.org/static/](https://alpha.de.repo.voidlinux.org/static/). - -``` -$ wget https://alpha.de.repo.voidlinux.org/static/xbps-static-latest.$(uname -m)-musl.tar.xz -``` - -After [verifying the integrity](#verifying-integrity) you can extract and use the binaries. - -``` -$ tar xfv xbps-static-latest.$(uname -m)-musl.tar.xz -$ ./usr/bin/xbps-install -h -``` - -### Verifying integrity - -The image release directories contain a `sha256sums.txt` and a -`sha256sums.txt.asc` file to verify the integrity of the downloaded images. - -``` -$ wget http://alpha.de.repo.voidlinux.org/live/current/sha256sums.txt{,.asc} -``` - -You can now verify the integrity of downloaded file using [sha256sum(1)](https://man.voidlinux.org/sha256sum.1). - -``` -$ sha256sum -c --ignore-missing sha256sums.txt -void-live-x86_64-musl-20170220.iso: OK -``` - -This just makes sure that the file was not corrupted while downloading. - -To verify that the downloaded files are the ones that the Void Linux maintainers published and signed you can use pgp. - -The file is signed with Juan RP’s GPG key: -* Signer: `Juan RP ` -* KeyID: `482F9368` -* Fingerprint: `F469 EAEF 52F5 9627 75B8 20CD AF19 F6CB 482F 9368` - -You can use [gpg(1)](https://man.voidlinux.org/gpg.1) to receive the key from a keyserver using the following command or download it from [https://alpha.de.repo.voidlinux.org/live/xtraeme.asc](https://alpha.de.repo.voidlinux.org/live/xtraeme.asc). - -``` -$ gpg --recv-keys 482F9368 -gpg: key AF19F6CB482F9368: public key "Juan RP " imported -gpg: marginals needed: 3 completes needed: 1 trust model: pgp -gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u -gpg: next trustdb check due at 2018-03-18 -gpg: Total number processed: 1 -gpg: imported: 1 -``` - -You can now verify the signature of the `sha256sums.txt` file with [gpg(1)](https://man.voidlinux.org/gpg.1). - -``` -$ gpg --verify sha256sums.txt.asc -gpg: assuming signed data in 'sha256sums.txt' -gpg: Signature made Wed 22 Feb 2017 02:59:20 AM CET -gpg: using RSA key AF19F6CB482F9368 -gpg: Good signature from "Juan RP " [unknown] -gpg: aka "Juan RP " [unknown] -gpg: aka "[jpeg image of size 3503]" [unknown] -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: F469 EAEF 52F5 9627 75B8 20CD AF19 F6CB 482F 9368 -``` - -## Using the Installer - -The installer has to be executed as `root` user, if you logged in as `anon` you can use [sudo(8)](https://man.voidlinux.org/sudo.8) to run the installer as `root`. - -## Manual installation - -## Post installation - -# System Management - -## System services and daemons - -Void uses the [runit](/usage/runit/) supervision suite to run system services and daemons. - -Services are enabled by simply linking them into the `/var/service` service directory. - -``` -# ln -s /etc/sv/ /var/service/ -``` - -To disable them again you just remove the link. - -``` -# rm /var/service/ -``` - -Activated services can be controlled with the [sv(8)](https://man.voidlinux.org/sv.8) command, following commands are available and can be used like `sv `. - -* `up` to start, `down` to stop and `once` to start services once. -* `pause`, `cont`, `hup`, `alarm`, `interrupt`, `quit`, `1`, `2`, `term` and `kill` to send the corresponding signal. -* `start`, `stop`, `reload` and `restart` for LSB init compatibility. - -See the [sv(8)](https://man.voidlinux.org/sv.8) manual page for further informations. - -The `status` command can be used to retrieve the current status of one or more services. -It accepts either service names or service directories, which makes it possible to use shell wildcards to retrieve the status for all activated services. - -``` -# sv status dhcpcd -run: /var/service/dhcpcd: (pid 659) 561392s -# sv status /var/service/* -run: /var/service/agetty-tty1: (pid 658) 561392s -run: /var/service/agetty-tty2: (pid 639) 561392s -run: /var/service/agetty-tty3: (pid 662) 561392s -run: /var/service/agetty-ttyS0: (pid 650) 561392s -run: /var/service/dhcpcd: (pid 659) 561392s -run: /var/service/nanoklogd: (pid 666) 561391s -run: /var/service/ntpd: (pid 665) 561391s; run: log: (pid 664) 561391s -run: /var/service/opensmtpd: (pid 661) 561392s -run: /var/service/socklog-unix: (pid 646) 561392s; run: log: (pid 645) 561392s -run: /var/service/sshd: (pid 674) 561391s -run: /var/service/udevd: (pid 660) 561392s -run: /var/service/uuidd: (pid 640) 561392s -``` - -Extra options can be passed to most services using a `conf` file in the service directory. - -``` -$ cat /etc/sv/sshd/run -#!/bin/sh -ssh-keygen -A >/dev/null 2>&1 # Will generate host keys if they don't already exist -[ -r conf ] && . ./conf -exec /usr/bin/sshd -D $OPTS -# echo 'OPTS="-p 2222"' >>/etc/sv/sshd/conf -``` - -Another example is the `wpa_supplicant` service which has other available variables. - -``` -# cat /etv/sv/wpa_supplicant/run -#!/bin/sh -[ -r ./conf ] && . ./conf -exec 2>&1 -exec wpa_supplicant -c ${CONF_FILE:=/etc/wpa_supplicant/wpa_supplicant.conf} -i ${WPA_INTERFACE:=wlan0} ${OPTS:=-s} -# echo WPA_INTERFACE=wlp3s0 >>/etc/sv/wpa_supplicant/conf -``` - -### Per user service directory - -Sometimes it would be nice to have user-specific runit services. Services that, -for example, open an ssh tunnel as your current user, run a virtual machine, -or regularly run daemons on your behalf. The most common way to do this to ask -a system-level runsv daemon to start a runsvdir daemon as your user for your -personal service directory. - -Create a service as `/etc/sv/$username/run` with the below contents: - -``` -#!/bin/sh - -UID=$(pwd -P) -UID=${UID##*/} - -if [ -d "/home/${UID}/service" ]; then - chpst -u"${UID}" runsvdir /home/${UID}/service -fi -``` - -Then you can create runit services and symlink them under ${HOME}/service and -then runit will take care of starting and restarting those services for you. - -One important caveat: if any services you have need group permissions instead -of just your user permissions, you will want to append those groups in a colon -separated list to your username, such as `/etc/sv/anon:void1:void2:void3/run` -instead of just `/etc/sv/anon/run`. - -### Cron - -Void Linux comes without a default cron daemon, you can choose one of multiple cron implementations, by installing the package and enabling the system service. - -Available choices include `cronie`, `dcron`, `fcron` and more. - -As alternative to the standard cron implementations you can use something like [snooze](https://github.com/chneukirchen/snooze) or `runwhen` which go hand in hand with service supervision. - -### Logging - -#### Syslog - -The default installation comes with no syslog daemon, there are different implementations available. - -`socklog` is the implementation from the [runit(8)](https://man.voidlinux.org/runit.8) author and Void Linux provides a package with some basic configuration for it, this makes it a good choice if you don't know which one to choose. - -``` -# xbps-install -S socklog-void -# usermod -aG socklog -# ln -s /etc/sv/socklog-unix /var/service/ -# ln -s /etc/sv/nanoklogd /var/service/ -``` - -Other syslog implementations like `rsyslog` and `metalog` are available in the package repository too. - -### Console (tty, getty, agetty) - -#### Disabling default ttys - -Void Linux enables [agetty(8)](https://man.voidlinux.org/agetty.8) services for the ttys 1 to 6 by default. - -To disable agetty services remove the service symlink and create a `down` file in the agetty service directory to avoid that updates of the `runit-void` package re-enable the service. - -``` -# rm /var/service/agetty-tty6 -# touch /etc/sv/agetty-tty6/down -``` - -## Changing the default shell - -The default shell for users can be changed with the [chsh(1)](https://man.voidlinux.org/chsh.1) tool. - -``` -$ chsh -s /bin/bash -``` - -Make sure to use the same path to the shell as its in `/etc/shells` or listed by the [chsh(1)](https://man.voidlinux.org/chsh.1) list command. - -A list of available installed shells can be retrieved with the [chsh(1)](https://man.voidlinux.org/chsh.1) list command. - -``` -$ chsh -l -/bin/sh -/bin/bash -/bin/mksh -/bin/zsh -/bin/rc -/bin/ksh -/bin/oksh -/bin/yash -``` - -Following packages are available in the package repository and provide usable shells. - -* bash -* dash -* elvish -* es -* fish-shell -* heirloom-sh -* ksh -* mksh -* oksh -* posh -* rc -* tcsh -* yash -* zsh - -## Kernel -### Kernel series - -Void Linux provides many kernel series in the default repository, - -``` -$ xbps-query --regex -Rs 'linux[34]' | grep -Ev '(dbg|headers)' -[-] linux3.14-3.14.79_1 The Linux kernel and modules (3.14 series) -[-] linux3.18-3.18.60_1 The Linux kernel and modules (3.18 series) -[-] linux4.1-4.1.41_1 The Linux kernel and modules (4.1 series) -[-] linux4.10-4.10.17_1 The Linux kernel and modules (4.10 series) -[*] linux4.11-4.11.11_1 The Linux kernel and modules (4.11 series) -[-] linux4.12-4.12.3_1 The Linux kernel and modules (4.12 series) -[-] linux4.13-4.13.0rc1_1 The Linux kernel and modules (4.13 series) -[-] linux4.4-4.4.76_1 The Linux kernel and modules (4.4 series) -[-] linux4.8-4.8.17_1 The Linux kernel and modules (4.8 series) -[-] linux4.9-4.9.37_1 The Linux kernel and modules (4.9 series) -``` - -The `linux` meta package which is installed by default depends on one of the kernel packages, usually the latest mainline kernel that works with all dkms modules. - -### Removing old kernels - -``` -$ vkpurge list -3.8.2_1 -``` - -You can now remove a specific kernel version like `3.8.2_1` or `all` which removes all kernels expect the latest kernel of each series and the kernel that is currently booted. - -``` -# vkpurge rm 3.8.2_1 -# vkpurge rm all -``` - -### Kernel modules -#### Loading kernel modules at boot - -To load kernel modules at boot time, a `.conf` file like `/etc/modules-load.d/virtio.conf` can be created. - -``` -# load virtio-net -virtio-net -``` - -#### Blacklisting kernel modules - -There are two different methods to blacklist kernel modules, for the initramfs and for the booted system. -Some modules are loaded by the initramfs very early in the boot process, those have to be blacklisted in the initramfs. - -You can blacklist modules with a `.conf` file like `/etc/modprobe.d/radeon.conf`. - -``` -blacklist radeon -``` - -##### dracut - -To blacklist modules from being included in a dracut initramfs you need to create a `.conf` file like `/etc/dracut.conf.d/radeon.conf`. - -``` -omit_drivers+=" radeon " -``` - -Now you need to regenerate the initramfs to make the changes take effect on the next reboot. - -``` -# dracut --force -``` - -##### mkinitcpio - -XXX: add example of blacklisting kernel modules for mkinitcpio - -### Kernel hooks - -Void Linux provides directories for kernel hooks in `/etc/kernel.d/{pre-install,post-install,pre-remove,post-remove}`. - -Bootloaders like `grub`, `gummiboot` and `lilo` use those hooks to update the bootmenu. Initramfs tools like `dracut` and `mkinitcpio` use the hooks to generate initramfs files for newly installed kernels. - -### Dynamic Kernel Module Support (dkms) - -There are kernel modules that are not part of the linux source tree that are build at install time using dkms and [kernel hooks](#kernel-hooks). - -``` -$ xbps-query -Rs dkms -[-] acpi_call-dkms-1.2.0_2 Kernel module allowing calls to ACPI methods through /proc/acpi/call -[-] dkms-2.4.0_2 Dynamic Kernel Modules System -[-] exfat-dkms-1.2.8_2 Exfat kernel driver (nofuse) -[-] spl-0.6.5.10_1 Solaris Porting Layer -- userland and kernel modules (using DKMS) -[-] tp_smapi-dkms-0.42_2 IBM ThinkPad hardware functions driver -[-] virtualbox-ose-dkms-5.1.24_1 General-purpose full virtualizer for x86 hardware - kernel module sources for dkms -[-] virtualbox-ose-guest-dkms-5.1.24_1 General-purpose full virtualizer for x86 hardware - guest addition module source for dkms -[-] zfs-0.6.5.10_1 Z File System -- userland and kernel modules (using DKMS) -[-] zfs-32bit-0.6.5.10_1 Z File System -- userland and kernel modules (using DKMS) (32bit) -[-] broadcom-wl-dkms-6.30.223.271_6 Broadcom proprietary wireless drivers for Linux - DKMS kernel module -[-] catalyst-dkms-15.302_2 AMD catalyst driver 15.12 for Linux - DKMS kernel module -[-] nvidia-dkms-381.22_2 NVIDIA drivers for linux (long-lived series) - DKMS kernel module -[-] nvidia304-dkms-304.135_4 NVIDIA drivers (For GeForce 5 FX, 6, 7, 8 series) - DKMS kernel module -[-] nvidia340-dkms-340.102_5 NVIDIA drivers (GeForce 8, 9, 9M, 100, 100M, 200, 300 series) - DKMS kernel module -``` - -### cmdline - -#### grub - -Kernel command line arguments can be added through the grub bootloader by editing `/etc/default/grub` and changing the `GRUB_CMDLINE_LINUX_DEFAULT` variable and then regenerating the grub configuration. - -``` -# vi /etc/default/grub -# grub-mkconfig -o /boot/grub/grub.cfg -``` - -#### dracut - -Dracut can be configured to add additional cmdline arguments to the kernel by creating a configuration file and regenerating the initramfs, make sure to reconfigure the right kernel version like `linux4.12` as example. - -``` -# mkdir -p /etc/dracut.conf.d -# echo 'kernel_cmdline+=""' >> /etc/dracut.conf.d/cmdline.sh -# xbps-reconfigure -f linux4.12 -``` - -## Manual pages - -Void packages come with manual pages and the default installation includes the [mandoc](http://mandoc.bsd.lv/) manpage toolset. - -The [man(1)](https://man.voidlinux.org/man.1) command can be used to show manual pages. - -``` -$ man 1 chroot -``` - -The [mandoc](http://mandoc.bsd.lv/) toolset contains [apropos(1)](https://man.voidlinux.org/apropos.1) to search for manual pages, [apropos(1)](https://man.voidlinux.org/apropos.1) uses a database that can be updated and generated with the [makewhatis(1)](https://man.voidlinux.org/makewhatis.1) command. - -``` -# makewhatis -a -$ apropos chroot -chroot(1) - run command or interactive shell with special root directory -xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces -xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces -xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces -xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces -chroot(2) - change root directory -``` - -There are two extra packages for development and POSIX manuals that are not installed by default. - -``` -$ xbps-query -Rs man-pages -[*] man-pages-4.11_1 Linux Documentation Project (LDP) manual pages -[-] man-pages-devel-4.11_1 Linux Documentation Project (LDP) manual pages - development pages -[-] man-pages-posix-2013a_3 Manual pages about POSIX systems -# xbps-install -S man-pages-devel man-pages-posix -``` - -# Packages - -Void Linux uses its home grown package management system, `xbps`. - -## Package Management -### Searching a file - -To search a file in packages you can use one of two methods - -The first method is to use [xbps-query(1)](https://man.voidlinux.org/xbps-query.1) which is okay to use if you want to just look for local files, you can use it to search for remote files with the `-R` flag but its very slow compared to the second method using `xlocate`. - -``` -$ xbps-query -o /usr/bin/xlocate -xtools-0.46_1: /usr/bin/xlocate (regular file) -``` - -The `xtools` package contains the `xlocate` utility that works like [locate(1)](https://man.voidlinux.org/locate.1) but for all files in the void package repository. - -``` -# xbps-install -Su xtools -$ xlocate -S -From https://alpha.de.repo.voidlinux.org/xlocate/xlocate - + 16d97bfe86...2ad1a4a8d1 master -> master (forced update) -$ xlocate fizz -nim-0.17.0_1 /usr/lib/nim/examples/fizzbuzz.nim -ponysay-3.0.2_1 /usr/share/ponysay/ponies/cherryfizzy.pony -> /usr/share/ponysay/ponies/cherrycola.pony -ponysay-3.0.2_1 /usr/share/ponysay/ttyponies/cherryfizzy.pony -> /usr/share/ponysay/ttyponies/cherrycola.pony -supertux2-data-0.5.1_1 /usr/share/supertux2/sounds/fizz.wav -``` - -## Building Packages - -The first step is to building xbps packages from source is to clone the `void-packages` [git(1)](https://man.voidlinux.org/git.1) repository. - -``` -$ git clone https://github.com/void-linux/void-packages.git -Cloning into 'void-packages'... -remote: Counting objects: 398517, done. -remote: Total 398517 (delta 0), reused 1 (delta 0), pack-reused 398516 -Receiving objects: 100% (398517/398517), 151.18 MiB | 5.10 MiB/s, done. -Resolving deltas: 100% (227465/227465), done. -``` - -After cloning the repository it is necessary to setup the build environment by bootstrapping a container/chroot using the `xbps-src` script. - -To bootstrap a build environment using binary packages for the same architecture your host uses use `binary-bootstrap`. - -``` -$ ./xbps-src binary-bootstrap -=> Installing bootstrap from binary package repositories... -[...] -=> Installed bootstrap successfully! -``` - -If you have the time and you want to build the bootstrap from source too, use the `bootstrap` command. - -``` -$ ./xbps-src bootstrap -``` - -In case you want to compile `i686` packages on your `x86_64` machine you can use one of the bootstrap commands with a different masterdir and the target architecture as second argument. - -``` -$ ./xbps-src -m masterdir-i686 binary-bootstrap i686 -=> Installing bootstrap from binary package repositories... -[...] -=> Installed bootstrap successfully! -``` - -You can now build packages using the `pkg` command. - -``` -$ ./xbps-src pkg vim -[...] -``` - -Or in case you bootstrapped a different masterdir for another native architecture. - -``` -$ ./xbps-src -m masterdir-i686 pkg vim -[...] -``` - -## Contributing - -You can find an extensive contributing guide [CONTRIBUTING.md](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md) in the `void-packages` git repository. - -## Debugging packages - -Void Linux packages come without debugging symbols, if you want to debug software or look at a coredump it is helpful to have the debugging symbols. -To get debugging symbols for packages you need to activate the debug repo, afterwards its possible to install packages with the `-dbg` suffix. - -``` -$ xbps-install -S void-repo-debug -$ xbps-install -S -dbg -``` - -The `xtools` package contains the `xdbg` utility to retrieve a list of debug packages including dependencies for a package. - -``` -$ xdbg bash -bash-dbg -glibc-dbg -# xbps-install -S $(xdbg bash) -``` - -## Available Mirrors - -| Repository | Location | -|:--------|:-------:| -| [https://alpha.de.repo.voidlinux.org/current/](https://alpha.de.repo.voidlinux.org/current/) | DE | -| [http://beta.de.repo.voidlinux.org/current/](http://beta.de.repo.voidlinux.org/current/) | DE | -| [http://alpha.us.repo.voidlinux.org/current/](http://alpha.us.repo.voidlinux.org/current/) | US | -| [http://mirror.clarkson.edu/voidlinux/current/](http://mirror.clarkson.edu/voidlinux/current/) | US | -| [http://www.gtlib.gatech.edu/pub/VoidLinux/current/](http://www.gtlib.gatech.edu/pub/VoidLinux/current/) | US | -| [http://mirror.aarnet.edu.au/pub/voidlinux/current/](http://mirror.aarnet.edu.au/pub/voidlinux/current/) | AU | - -## Changing mirrors - -Copy all repository configuration files from `/usr/share/xbps.d` to `/etc/xbps.d` and then change the repository urls in `/etc/xbps.d`. - -``` -# mkdir -p /etc/xbps.d -# cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/ -# sed -i 's|https://alpha.de.repo.voidlinux.org/current||g' /etc/xbps.d/*-repository-*.conf -``` - -You can use `xbps-query` to verify that all repositories are changed to the mirror you prefer. - -``` -$ xbps-query -L - 8175 https://alpha.de.repo.voidlinux.org/current (RSA signed) - 23 https://alpha.de.repo.voidlinux.org/current/multilib/nonfree (RSA signed) - 3360 https://alpha.de.repo.voidlinux.org/current/multilib (RSA signed) - 44 https://alpha.de.repo.voidlinux.org/current/nonfree (RSA signed) - 4357 https://alpha.de.repo.voidlinux.org/current/debug (RSA signed) -``` - -# Disk Setup - -# Networking - -The Network configuration in Void Linux can be done with different methods, the -default installation comes with [dhcpcd(8)](https://man.voidlinux.org/dhcpcd.1). - -## Interface names - -In newer versions udev changed the well known traditional naming scheme (`eth0`, `eth0`, `wlan0`, ...). -This behaviour can be reverted by adding `net.ifnames=0` to the [kernel cmdline](#cmdline). - -## Static Setup - -A static network in Void Linux can be configured with [ip(8)](https://man.voidlinux.org/ip.8). - -A simple way to configure the static network at boot is to add the necessary [ip(8)](https://man.voidlinux.org/ip.8) commands to the `/etc/rc.local` file. - -``` -# Static IP configuration via iproute -ip link set dev eth0 up -ip addr add 192.168.1.2/24 brd + dev eth0 -ip route add default via 192.168.1.1 -``` - -## DHCP - -### dhcpcd - -To run `dhcpcd` on all interfaces you can enable the `dhcpcd` service. - -``` -# ln -s /etc/sv/dhcpcd /var/service -``` - -If you want to run dhcpcd just on a specific interface you can use the `dhcpcd-eth0` service if this matches your interface name. -Otherwise you can just copy `dhcpcd-eth0` and change it to match your interface. - -``` -$ ip link show -1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 -2: enp3s0: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 - link/ether ff:ff:ff:ff:ff:ff brd ff:ff:ff:f -# cp -R /etc/sv/dhcpcd-eth0 /etc/sv/dhcpcd-enp3s0 -# sed -i 's/eth0/enp3s0/' /etc/sv/dhcpcd-enp3s0/run -# ln -s /etc/sv/dhcpcd-enp3s0 /var/service -``` - -### dhclient -### NetworkManager -### wicd - -## wpa_supplicant - -# Xorg - -## Drivers - -## Display managers - -## Session and seat management - -Session and seat management is not necessary for every setup, it is used to provide device access on the fly for the currently active user session. - -For desktop environments like Gnome [elogind](#elogind) is necessary. - -### ConsoleKit2 - -Install ConsoleKit2 and activate its service and make sure the dbus and the cgmanager services are activated too. - -``` -# xbps-install -S ConsoleKit2 -# ln -s /etc/sv/dbus /var/service/ -# ln -s /etc/sv/cgmanager /var/service/ -# ln -s /etc/sv/consolekit /var/service/ -``` - -If you don't use a display manager or your display manager doesn't start a ConsoleKit2 session on its own you need to start a ConsoleKit2 session from your `.xinitrc`. ConsoleKit2 comes with a `xinitrc.d` script (`/etc/X11/xinit/xinitrc.d/90-consolekit`) which sets the `STARTUP` variable to the appropriate way to start the session. - -The following `.xinitrc` script sources all scripts in `/etc/X11/xinit/xinitrc.d` and starts the window manager of your choice with a session. - -``` -#!/bin/sh -# -# ~/.xinitrc -# -# Executed by startx (run your window manager from here) - -if [ -d /etc/X11/xinit/xinitrc.d ]; then - for f in /etc/X11/xinit/xinitrc.d/*; do - [ -x "$f" ] && . "$f" - done - unset f -fi - -exec $STARTUP -``` - -### elogind - -``` -# xbps-install -S elogind -``` - -# Multimedia - -## Audio setup -To setup audio on your Void Linux system you have to decide if you want to use [PulseAudio](#pulseaudio) or just [alsa](#alsa). - -Some applications require PulseAudio, especially closed source programs. - -### Alsa - -Install the `alsa-utils` package make sure your user is part of the `audio` group to access audio devices. - -``` -# xbps-install -S alsa-utils -# usermod -a -G audio -``` - -The `alsa-utils` package comes with the system service `/etc/sv/alsa` which can be activated to save and restore the state of alsa controls like the volume at shutdown and boot respectively. - -If the soundcard you want to use is not the default you can either use kernel module options or the alsa config to change the default card. - -The current module order can be retrieved from the procfs filesystem. - -``` -$ cat /proc/asound/modules - 0 snd_hda_intel - 1 snd_hda_intel - 2 snd_usb_audio -``` - -To use the kernel module options you can create a file like `/etc/modprobe.d/alsa.conf` with following content. - -``` -options snd_usb_audio index=0 -``` - -Alternatively using the alsa configuration file `/etc/asound.conf` or the per-user configuration file `~/.asoundrc` to set a different card as the default. - -``` -defaults.ctl.card 2; -defaults.pcm.card 2; -``` - -### PulseAudio - -PulseAudio depends on a `dbus` system daemon, make sure its enabled. - -``` -# xbps-install -S alsa-utils pulseaudio -# ln -s /etc/sv/dbus /var/service/ -``` - -The PulseAudio package comes with a services file, which is not necessary in most setups and its [discouraged](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SystemWide/) by the PulseAudio maintainers to use the system wide setup. - -There are different methods that work with PulseAudio to allow access to the audio devices, the simplest one is to just the `audio` group alternatively you can use a session manager, like [elogind](#elogind) or [ConsoleKit2](#consolekit2).