Puppet module for configuring various aspects of an Arch Linux workstation/desktop.
Ruby Puppet Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with archlinux_workstation
  4. Requirements
  5. Usage - Configuration options and additional functionality
  6. Reference - An under-the-hood peek at what the module is doing and how
  7. Limitations - OS compatibility, etc.
  8. Development - Guide for contributing to the module


Project Status: Active - The project has reached a stable, usable state and is being actively developed.

Provides many classes for configuring an Arch Linux workstation/laptop/desktop for graphical use and installing common software.

Module Description

This is one of the modules that I use to keep my personal desktop and work laptop, both running Arch Linux, in sync, up to date, and easily rebuild-able. It's intended to do three main things:

  1. Manage all installed packages, and all configuration outside of /home, so I don't need to back up anything outside /home.
  2. Keep my desktop and laptop perfectly in sync in terms of packages and global (non-user-specific) configuration.
  3. Allow me to quickly rebuild one of these machines if needed, to minimize downtime.

This module is intended to be part of a whole. For me, that includes my workstation-bootstrap module (GitHub) that uses r10k, a Puppetfile, and a few manifests to actually manage what's applied to my machines and install modules, as well as a private module ("privatepuppet") on GitHub for my sensitive/personal configuration, and a specific module for Arch Linux on my MacBook Pro Retina that handles some things specific to that platform.

Note: this module is quite opinionated; it is how I setup my machines, and may not be exactly what you want. Pull requests are welcome to add parameters for more control over its behavior.


What archlinux_workstation affects

See the Reference section below for details. In general, the goal is that it affects anything and everything you'd need to touch to take a base Arch Linux installation to a fully-usable, graphical workstation/laptop/desktop. This includes:

  • your login user, a primary group with the same name as the username, and their supplementary groups


  • sudoers file and sudoers.d entries for your user
  • sshd_config, including AllowUsers (your user only) and auth methods (pubkey/RSA only)
  • /etc/makepkg.conf, set to compile and cache sources under /tmp (tmpfs), and specify -j${::processorcount} make flag.
  • installation of some common base packages (see archlinux_workstation::base_packages below)
  • use of the puppetlabs/firewall module to manage iptables (note that it's expected you setup the module elsewhere, as I do in workstation_bootstrap - this module just adds rules for its services using the Firewall type).
  • enable dkms support by installing the package and enabling the service
  • creates and uses a swapfile at a configurable path and of configurable size (by defaylt, 4G at /swapfile), via an instance of archlinux_workstation::swapfile.
  • sets up CUPS printing
  • sets up the Chrony alternative NTP daemon
  • installs Xorg Xserver as well as related required and recommended/optional packages (note - this currently only installs the default vesa driver. See archlinux_workstation::xorg below for more information)
  • if the gui parameter is set to 'kde' (default), installs KDE Plasma and installs and runs SDDM
  • sets up my personal (jantman) pacman repo and the Multilib repo
  • installation of a number of different user applications (see archlinux_workstation::userapps:: classes below)


TODO - document other requirements


Classes are parameterized where that makes sense. Right now, there are two methods of usage:

  1. To install and setup everything this module is capable of, declare an instance of archlinux_workstation passing the username parameter for the name of your user, and an instance of archlinux_workstation::all to do everything.

    class {'archlinux_workstation': foo => bar, }

    class {'archlinux_workstation::all': }

  2. To pick and choose which parts you use, declare archlinux_workstation as shown above, and in place of archlinux_workstation::all, declare the classes that you want.

If you stick to one of these two usage methods (instead of forking this module and hacking on the internals), you should be safe to pull in updates as they happen.



Declares your user and group, and sets a few variables used by other classes.


  • username - (string) Your login username. Used to create your account, add you to certain groups, etc. Default: undef.
  • realname - (string) The user's real name, to be used in the passwd comment/GECOS field. Defaults to $username if not specified.
  • user_home - Path to $username's home directory. Used for classes that put files in the user's home directory. Default: "/home/${username}".
  • shell - (string) the user's login shell. Default: '/bin/bash'
  • user_groups - (array) list of supplementary groups that this user should be a member of. Default: ['sys']


Collection of base packages that we want installed on every system.

  • ensure Package lynx is absent
  • ensure Packages are present: links, lsb-release, dmidecode, ttf-dejavu, vim, wget, bind-tools, net-tools, lsof, screen


Install and configure chrony, a roaming/laptop friendly NTP client, as well as the networkmanager-dispatcher-chrony script for it.


Install and run the cronie cron daemon. Per the Arch wiki cron entry, no cron daemon comes default with Arch.


  • chrony_password - The password that other clients will use to connect to chrony. Our configuration only has chrony listening on localhost/, so this shouldn't be important. Default: 'd83ja72.f83,8wHUW94'


Installs CUPS printing.

  • installs cups and a list of related packages
  • runs the cups service


Enable DMKS support

  • ensure Package dkms is present
  • ensure Service dkms is enabled and running


Perform a full installation of KDE/Plasma via the "plasma-meta" and "kde-applications-meta" package groups, as well as Phonon.


Sets up /etc/makepkg.conf with sane Arch defaults, including compiling and caching sources under /tmp (tmpfs), and passing make the -j flag with an argument of the number of processors/cores on the machine, as retrieved from the "processorcount" fact.


  • make_flags - (string) additional flags to pass to make via makepkg.conf. default: "-j${::processorcount}"


Install and setup networkmanager its GUI components, and ensure dhcpcd is stopped and nm is running. If archlinux_workstation::kde is defined, install kdeplasma-applets-networkmanagement.


Enable my personal (jantman) pacman repo.


Enable the Multilib repo.


Install and run SDDM desktop manager.


Wrapper around saz/ssh to configure SSH server.


  • allow_users - Array of usernames to allow to login via SSH. If left default (undef), [$archlinux_workstation::username] will be used. If $::virtual == virtualbox, "vagrant" will be appended to the list.


Sets up sudo, global defaults, and permissions for your user. This class simply wraps saz/sudo.

Define archlinux_workstation::swapfile

Creates a swap file, makes swap, activates it and adds it to fstab

This class uses some execs to create the swapfile, then execs swapon and uses Augeas to add the swapfile to /etc/fstab.


  • swapfile_path - (string) path where the swapfile will be stored. Default: '/swapfile'. Must be an absolute path.

  • swapfile_size - (string) size of the swapfile, in format allowed by fallocate, i.e. a bare integer number of bytes, or an integer followed by K, M, G, T and so on for KiB, MiB, GiB, TiB, etc. Default: '4G'. NOTE that at this time, this module will not recreate swapfiles, so if you change this parameter, it will have no effect unless you swapoff and remove the old swapfile.


Define to install rvm for a single user in their home directory.


Install and configure VirtualBox and Vagrant.


Install packages required for xorg X server, as well as some additional packages.

Note - currently this just installs the default "xf86-video-vesa" driver. Need to write a fact to find video cards and choose the correct driver, per Driver Installation, or expose this option to the user as a parameter.


This module is only usable with Arch Linux.

It assumes that you have a relatively vanilla base install of Arch, such as the one I document in my workstation-bootstrap module, pretty much the same as the Arch Linux Installation Guide documents.


See CONTRIBUTING.md for information about development and contributing.

This module currently just has spec tests; run them with:

bundle install --path vendor
bundle exec rake spec

Adding Classes

To add a class:

  1. Add the class itself, using the template: sed 's/CLASSNAME/name_of_class/g' manifests/template.txt > manifests/name_of_class.pp
  2. Add spec tests, using the template: sed 's/CLASSNAME/name_of_class/g' spec/classes/template.txt > spec/classes/name_of_class.pp
  3. Add acceptance tests.
  4. Add the class to the Reference section above
  5. Add the class to the archlinux_workstation::all (manifests/all.pp) class.