NixOS Wiki

Extend NixOS: Difference between revisions

← Older edit
VisualWikitext
imported>Fadenb
Pigs (talk | contribs)
259 edits
→Quick Implementation: Use current channel for search.nixos.org link
Tags: Mobile edit Mobile web edit Advanced mobile edit
 
(24 intermediate revisions by 13 users not shown)
Line 1: Line 1:
This tutorial covers the major points of NixOS configuration. In this tutorial, we configure NixOS to start an IRC client every time the OS starts. This tutorial will  start by adding this functionality to the <code>configuration.nix</code> file. Then, this functionality is extracted into a separate file, which NixOS calls a "module".
This tutorial shows how to extend a NixOS configuration to include custom [[systemd]] units, by creating a [[systemd]] unit that initializes IRC client every time a system session starts. Beginning by adding functionality directly to a {{ic|configuration.nix}} file, it then shows how to abstract the functionality into a separate NixOS [[module]].  


= Example: Add a System Service =
= The Problem =


Suppose you want to start an IRC client and connect to your favorite channel every time your NixOS starts. To do this, we will start the IRC client using a shell command. In other distributions, to perform an action on system start, you place the shell command in an init script, which is usually the <code>/etc/init.d</code> file.
We want to start up an IRC client whenever a user logs into/starts their session.


In NixOS, on the other hand, all system files are overwritten when the <code>configuration.nix</code> file is updated and the system is rebuilt. How does a NixOS user execute a shell command on system start? In NixOS, all dependencies are clean and organized, which means they are changed in a single place - the <code>configuration.nix</code> and the modules it loads. To change the system's behavior, then, we must add this IRC shell command to this configuration file.
It is possible to find a variety of different ways to do this, but a simple modern approach that fits well within NixOS's [[Declarative model]] is to declare a {{ic|systemd}} unit which initializes the IRC client upon session login by a user.


Lets start the IRC session using <code>irssi</code> as the IRC client. We'll run it inside a <code>screen</code> daemon, which enables the IRC session to continue even after we log out of our shell session.
Assume that our IRC client is {{ic|irssi}} as the IRC client. We'll run it inside a [https://wiki.archlinux.org/title/GNU_Screen screen] daemon, which apart from allowing us to [https://en.wikipedia.org/wiki/Terminal_multiplexer multiplex] our terminal sessions, also enables the IRC session to continue even after we log out of our shell session.
 
Note that due to the details of systemd, the service we create will run *per user*, not *per session*.
 
= Some helpful links =
 
This article assumes some familiarity with [[systemd]], and [[NixOS options]]. The following links will be helpful for providing this background:
 
* General overviews of {{ic|systemd}}: [https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system_administrators_guide/chap-managing_services_with_systemd from RedHat], [https://wiki.archlinux.org/title/Systemd the Arch Linux Wiki], [https://www.digitalocean.com/community/tutorials/how-to-use-systemctl-to-manage-systemd-services-and-units tutorial from Digital Ocean]
* [https://www.freedesktop.org/software/systemd/man/latest/systemd.html# systemd man pages]
* NixOS [[ modules ]]
* use  [[NixOS search|NixOS Search]]  and [https://nixos.org/nixos/manual/options.html NixOS Manual: List of Options] to look up more information about specific module options that we use


= Implementations =
= Implementations =
Line 13: Line 24:
== Quick Implementation ==
== Quick Implementation ==


The simplest way to implement this is to add a simple snippet of code to the <code>/etc/nixos/configuration.nix</code> file:
NixOS provides [https://search.nixos.org/options?show=systemd a systemd module] with a wide variety of configuration options. A small number of those (which you can check out on [[ NixOS search ]]) allows us to implement this little snippet within our {{ic|configuration.nix}}:


{pkgs, ...}:
<syntaxhighlight lang="nix">
  # pkgs is used to fetch screen & irssi.
  # pkgs is used to fetch screen & irssi.
 
{pkgs, ...}:
  {
  {
   jobs.ircSession = {
   # ircSession is the name of the new service we'll be creating
    description = "Start the irc client of username.";
  systemd.services.ircSession = {
    startOn = "started network-interfaces";
      # this service is "wanted by" (see systemd man pages, or other tutorials) the system
    exec = <nowiki>''/var/setuid-wrappers/sudo -u username -- ${pkgs.screen}/bin/screen -m -d -S irc ${pkgs.irssi}/bin/irssi'';</nowiki>
      # level that allows multiple users to login and interact with the machine non-graphically
      # (see the Red Hat tutorial or Arch Linux Wiki for more information on what each target means)
      # this is the "node" in the systemd dependency graph that will run the service
      wantedBy = [ "multi-user.target" ];
      # systemd service unit declarations involve specifying dependencies and order of execution
      # of systemd nodes; here we are saying that we want our service to start after the network has
      # set up (as our IRC client needs to relay over the network)
      after = [ "network.target" ];
      description = "Start the irc client of username.";
      serviceConfig = {
        # see systemd man pages for more information on the various options for "Type": "notify"
        # specifies that this is a service that waits for notification from its predecessor (declared in
        # `after=`) before starting
        Type = "notify";
        # username that systemd will look for; if it exists, it will start a service associated with that user
        User = "username";
        # the command to execute when the service starts up
        ExecStart = ''${pkgs.screen}/bin/screen -dmS irc ${pkgs.irssi}/bin/irssi'';  
        # and the command to execute       
        ExecStop = ''${pkgs.screen}/bin/screen -S irc -X quit'';
      };
   };
   };
   
   
   environment.systemPackages = [ pkgs.screen ];
   environment.systemPackages = [ pkgs.screen ];
  security.sudo.enable = true;
   
   
   # ... usual configuration ...
   # ... usual configuration ...
  }
  }
</syntaxhighlight>


What does this do? The <code>jobs.ircSession</code> bit is an option which adds a new system service. This option is defined elsewhere in the NixOS configuration files. This is one of many options; you can see a list of all NixOS configuration options in the [https://nixos.org/nixos/manual/options.html NixOS Manual: List of Options]. We add attributes to this option to configure our new service. As you can see, we configure it to start when the network connects, and to execute a shell command.
What does this do?  
* <code>systemd.services.ircSession</code> option adds our new service to the {{ic|systemd}} module's {{ic|services}} [https://search.nixos.org/options?channel=unstable&show=systemd.services&from=0&size=50&sort=relevance&type=packages&query=systemd.service attribute set].
 
* The comments explain the various configuration steps declaring the definition of the new service. As you can see, we configure it to start when the network connects, and to execute a shell command.


After rebuilding the NixOS configuration with this file, our IRC session should start when our network connects. The IRC session is started as a child to the screen daemon, which is independent of any user's session and will continue running when we log out. To connect to the IRC session, we SSH into the system, reconnect to the screen session, and choose the IRC window. Here's the command:
After rebuilding the NixOS configuration with this file, our IRC session should start when our network connects. The IRC session is started as a child to the screen daemon, which is independent of any user's session and will continue running when we log out. To connect to the IRC session, we SSH into the system, reconnect to the screen session, and choose the IRC window. Here's the command:


  ssh username@my-server -t screen -d -R irc
{{ ic | # ssh username@my-server -t screen -d -R irc }}
 
=== Using systemd ===
 
NixOS is now using systemd by default, and thus the way to define nix modules has changed.  Here's the commented equivalent of the snippet above:
 
  {
    systemd.services.ircSession = {
      wantedBy = [ "multi-user.target" ];
      after = [ "network.target" ];
      serviceConfig = {
        Type = "forking";
        User = "username";
        ExecStart = <nowiki>''${pkgs.screen}/bin/screen -dmS irc ${pkgs.irssi}/bin/irssi''</nowiki>;       
        ExecStop = <nowiki>''${pkgs.screen}/bin/screen -S irc -X quit''</nowiki>;
      };
    };
  }


== Conditional Implementation ==
== Conditional Implementation ==
Line 60: Line 76:


We can use the <code>mkIf</code> function in the <code>configuration.nix</code> file to add conditional behavior. Here's the new implementation:
We can use the <code>mkIf</code> function in the <code>configuration.nix</code> file to add conditional behavior. Here's the new implementation:
 
<syntaxhighlight lang="nix">
  {config, pkgs, ...}:
  {config, pkgs, lib, ...}:
   
   
  {
  {
   jobs = pkgs.lib.mkIf (config.networking.hostname == "my-server") {
   systemd.services = lib.mkIf (config.networking.hostName == "my-server") {
    ircSession = {
      ircSession = {
      description = "Start the irc client of username.";
        wantedBy = [ "multi-user.target" ];
      startOn = "started network-interfaces";
        after = [ "network.target" ];
      exec = <nowiki>''/var/setuid-wrappers/sudo -u username -- ${pkgs.screen}/bin/screen -m -d -S irc ${pkgs.irssi}/bin/irssi'';</nowiki>
        description = "Start the irc client of username.";
    };
        serviceConfig = {
          Type = "forking";
          User = "username";
          ExecStart = ''${pkgs.screen}/bin/screen -dmS irc ${pkgs.irssi}/bin/irssi'';        
          ExecStop = ''${pkgs.screen}/bin/screen -S irc -X quit'';
        };
      };
   };
   };
   
   
   environment.systemPackages = pkgs.lib.mkIf (config.networking.hostname == "my-server") [ pkgs.screen ];
   environment.systemPackages = lib.mkIf (config.networking.hostName == "my-server") [ pkgs.screen ];
  security.sudo.enable = (config.networking.hostname == "my-server");
   
   
   # ... usual configuration ...
   # ... usual configuration ...
  }
  }
 
</syntaxhighlight>
This works, but if we use too many conditionals, our code will become difficult to read and modify. For example, what do we do when we want to change the hostname?
This works, but if we use too many conditionals, our code will become difficult to read and modify. For example, what do we do when we want to change the hostname?


== Modular Configuration ==
== Modular Configuration ==


To avoid using conditional expressions in our <code>configuration.nix</code> file, we can separate these properties into units and blend them together differently for each host. Nix allows us to do this with the <code>imports</code> keyword (see [http://nixos.org/nixos/manual/#idp522432 NixOS Manual: Modularity]) to separate each concern into its own file. One way to organize this is to place common properties in the <code>configuration.nix</code> file and move the the IRC-related properties into an <code>irc-client.nix</code> file.
To avoid using conditional expressions in our <code>configuration.nix</code> file, we can separate these properties into units and blend them together differently for each host. Nix allows us to do this with the <code>imports</code> attribute (see [https://nixos.org/nixos/manual/index.html#sec-modularity NixOS Manual: Modularity]) to separate each concern into its own file. One way to organize this is to place common properties in the <code>configuration.nix</code> file and move the the IRC-related properties into an <code>irc-client.nix</code> file.


If we move the IRC stuff into the <code>irc-client.nix</code> file, we change the <code>configuration.nix</code> file like this:
If we move the IRC stuff into the <code>irc-client.nix</code> file, we change the <code>configuration.nix</code> file like this:
 
<syntaxhighlight lang="nix">
  {
  {
   imports = [
   imports = [
Line 93: Line 114:
   # ... usual configuration ...
   # ... usual configuration ...
  }
  }
 
</syntaxhighlight>
The <code>irc-client.nix</code> file will, of course, look like this:
The <code>irc-client.nix</code> file will, of course, look like this:
 
<syntaxhighlight lang="nix">
  {config, pkgs, ...}:
  {config, pkgs, lib, ...}:
   
   
  pkgs.lib.mkIf (config.networking.hostname == "my-server") {
  lib.mkIf (config.networking.hostName == "my-server") {
   jobs.ircSession = {
   systemd.services.ircSession = {
    description = "Start the irc client of username.";
      wantedBy = [ "multi-user.target" ];
    startOn = "started network-interfaces";
      after = [ "network.target" ];
    exec = <nowiki>''/var/setuid-wrappers/sudo -u username -- ${pkgs.screen}/bin/screen -m -d -S irc ${pkgs.irssi}/bin/irssi'';</nowiki>
      description = "Start the irc client of username.";
      serviceConfig = {
        Type = "forking";
        User = "username";
        ExecStart = ''${pkgs.screen}/bin/screen -dmS irc ${pkgs.irssi}/bin/irssi'';        
        ExecStop = ''${pkgs.screen}/bin/screen -S irc -X quit'';
      };
   };
   };
   
   
   environment.systemPackages = [ pkgs.screen ];
   environment.systemPackages = [ pkgs.screen ];
  security.sudo.enable = true;
}
}
</syntaxhighlight>
 
If we organize our configuration like this, sharing it across machines is easier. In addition, our IRC client can be consistent across machines that choose to use it.
If we organize our configuration like this, sharing it across machines is easier. In addition, our IRC client can be consistent across machines that choose to use it.


Line 117: Line 143:
NixOS supports this idea, but it is called "options". We can add options to our module for both the condition and the username. Here is what a <code>irc-client.nix</code> module with parameters/options looks like:
NixOS supports this idea, but it is called "options". We can add options to our module for both the condition and the username. Here is what a <code>irc-client.nix</code> module with parameters/options looks like:


<pre>
<syntaxhighlight lang="nix">
  {config, pkgs, ...}:
  {config, pkgs, lib, ...}:
   
   
  let
  let
Line 124: Line 150:
  in
  in
   
   
  with pkgs.lib;
  with lib;
   
   
  {
  {
Line 148: Line 174:
   
   
   config = mkIf cfg.enable {
   config = mkIf cfg.enable {
     jobs.ircSession = {
     systemd.services.ircSession = {
       description = "Start the irc client of ${cfg.user}.";
      wantedBy = [ "multi-user.target" ];
       startOn = "started network-interfaces";
      after = [ "network.target" ];
      exec = ''/var/setuid-wrappers/sudo -u ${cfg.user} -- ${pkgs.screen}/bin/screen -m -d -S irc ${pkgs.irssi}/bin/irssi'';
       description = "Start the irc client of username.";
       serviceConfig = {
        Type = "forking";
        User = "${cfg.user}";
        ExecStart = ''${pkgs.screen}/bin/screen -dmS irc ${pkgs.irssi}/bin/irssi'';       
        ExecStop = ''${pkgs.screen}/bin/screen -S irc -X quit'';
      };
     };
     };
   
   
     environment.systemPackages = [ pkgs.screen ];
     environment.systemPackages = [ pkgs.screen ];
    security.sudo.enable = true;
   };
   };
  }
  }
</pre>
</syntaxhighlight>


This module is now independent of the system. Now, we must update our <code>configuration.nix</code> file to pass our condition and hostname into our new module.
This module is now independent of the system. Now, we must update our <code>configuration.nix</code> file to pass our condition and hostname into our new module.


<pre>
<syntaxhighlight lang="nix">
{config, ...}:
{config, ...}:


Line 170: Line 201:
   ];
   ];
   
   
   services.ircClient.enable = config.networking.hostname == "my-server";
   services.ircClient.enable = config.networking.hostName == "my-server";
   services.ircClient.user = "username";
   services.ircClient.user = "username";
   
   
   # ... usual configuration ...
   # ... usual configuration ...
  }
  }
</pre>
</syntaxhighlight>
 
== Multiple Daemons ==
 
Now, suppose your server has multiple people as users, and each wants the same IRC client running in background. One possibility is to replace the user name with a list of user names.  A better solution, for this tutorial, is to '''extend''' the <code>jobs</code> option. This will allow us to add "IRC jobs", each of which is for a specific user. This should create configuration options like this:
 
jobs.ircClient.user  = "User1";
jobs.ircClient.enable = true;
 
The following code will add more options inside the <code>jobs.<name></code> option. This code is quite advanced, using many concepts from functional language paradigm.
 
<pre>
{config, pkgs, ...}:
let
  # Function which indicates whether the configuration defines any ircClient.
  anyIrcClient = with pkgs.lib;
    fold (j: v: v || j.ircClient.enable) (attrValues config.jobs);
in
with pkgs.lib;
{
  options = {
    # Add options to "jobs".
    jobs.options = {config, ...}: let
      cfg = config.ircClient;
    in {
      # The attributes in this set will merge into "jobs" set.
      options = {
       
        # Add "ircClient.enable" to "jobs" set of options.
        ircClient.enable = mkOption {
          default = false;
          type = with types; bool;
          description = ''
            Start an irc client for a user.
          '';
        };
        # Add "ircClient.user" to "jobs" set of options.
        ircClient.user = mkOption {
          default = "username";
          type = with types; uniq string;
          description = ''
            Name of the user.
          '';
        };
      };
      config = mkIf cfg.enable {
        description = "Start the irc client of ${cfg.user}.";
        startOn = "started network-interfaces";
        exec = ''/var/setuid-wrappers/sudo -u ${cfg.user} -- ${pkgs.screen}/bin/screen -m -d -S irc ${pkgs.irssi}/bin/irssi'';
      };
    };
  };
  # Execute this code if this configuration defined any ircClient.
  config = mkIf anyIrcClient {
    environment.systemPackages = [ pkgs.screen ];
    security.sudo.enable = true;
  };
}
</pre>


= Testing Configuration Changes in a VM =
= Testing Configuration Changes in a VM =
Line 247: Line 214:
To see how this works, create a file like this:
To see how this works, create a file like this:


<pre>
<syntaxhighlight lang="nix">
  {config, pkgs, ...}:
  {config, pkgs, ...}:
  {
  {
Line 274: Line 241:
   };
   };
  }
  }
</pre>
</syntaxhighlight>
 
Then, we build the new configuration inside a VM. If we named the above file <code>my-new-service.nix</code>, we can use these commands:


  ## Create a VM from the new configuration.
Then, we build the new configuration inside a VM. If we named the above file <code>vmtest.nix</code>, we can use these commands:
<syntaxhighlight lang="console">
  # Create a VM from the new configuration.
  $ NIXOS_CONFIG=`pwd`/vmtest.nix nixos-rebuild  -I nixos=/path/to/nixos/ build-vm
  $ NIXOS_CONFIG=`pwd`/vmtest.nix nixos-rebuild  -I nixos=/path/to/nixos/ build-vm
  ## Then start it.
  # Then start it.
  $ ./result/bin/run-vmhost-vm
  $ ./result/bin/run-vmhost-vm
</syntaxhighlight>


= What Next? =
= What Next? =
Line 289: Line 257:
If you have another tutorial about extending NixOS, add a link below.
If you have another tutorial about extending NixOS, add a link below.


* [http://larrythecow.org/archives/2011-10-11.html System Services on NixOS: larrythecow.org]
* [https://web.archive.org/web/20150331124128/http://larrythecow.org/archives/2011-10-11.html System Services on NixOS: larrythecow.org (archived)]
 
[[Category:systemd]]
[[Category:Tutorial]]
[[Category:NixOS]]
Retrieved from "https://wiki.nixos.org/wiki/Extend_NixOS"