NixOS Wiki

Extend NixOS: Difference between revisions

← Older editNewer edit →
VisualWikitext
imported>Qm3ster
m 1. imports is a config attribute, not to be confused with the import keyword 2. Fixed code to correspond to description
imported>Bzm3r
Simplifying language, focusing purpose.
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 [[{{ic|systemd}}]] units, by creating a [[{{ic|systemd}}]] unit 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 {{ic|screen}}] daemon, which apart from allowing us to {{multiplex}} our terminal sessions, also enables the IRC session to continue even after we log out of our shell session.


= Implementations =
= Implementations =
Line 13: Line 13:
== 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?channel=23.05&show=systemd a {{ic|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 small snippet within our {{ic|configuration.nix}}:
 
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{pkgs, ...}:
  # pkgs is used to fetch screen & irssi.
  # pkgs is used to fetch screen & irssi.
 
{pkgs, ...}:
  {
  {
 
  # ircSession is the name of the new service we'll be creating
   systemd.services.ircSession = {
   systemd.services.ircSession = {
      #
       wantedBy = [ "multi-user.target" ];  
       wantedBy = [ "multi-user.target" ];  
       after = [ "network.target" ];
       after = [ "network.target" ];
Line 38: Line 38:
  }
  }
</syntaxhighlight>
</syntaxhighlight>
What does this do? The <code>systemd.services.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] (or use https://search.nixos.org/options to search for 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? The <code>systemd.services.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] (or use https://search.nixos.org/options to search for 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.


Line 232: Line 233:
* [https://web.archive.org/web/20150331124128/http://larrythecow.org/archives/2011-10-11.html System Services on NixOS: larrythecow.org (archived)]
* [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:Tutorial]]
[[Category:NixOS]]
[[Category:NixOS]]
Retrieved from "https://wiki.nixos.org/wiki/Extend_NixOS"