Self-Help - Discovering the options / Looking up the reference

Development Documentation
1

Hi All,

I am still feeling very, very new to NixOS and whilst I have managed to build a new laptop using NixOS, install KVM and get running with working VMs, once again today I hit a personal road-block and ended up relying on ‘search’ as opposed to working my way through a relevant ‘configuration guide’ and checking any syntax with a ‘command reference’.

If I can illustrate the roadblock I had today perhaps I can share where as a new user I am getting stuck and you can guide me to right paths. I’m not looking for the answer to my particular question but how to find the answer myself.

So I wanted to create a private network (bridge) to connect two Virtual Machines (KVM) in configuration.nix. Going to the networking section of the user manual didn’t really cover this or point me in the right direction. I reverted to searching the NixOS wiki, discourse, google…

I came across this discourse post which led me to a useful link. The start of this showed me what looked like the right option;

  options = {
    virtualisation.libvirtd.networking = {
      enable = mkEnableOption "Enable nix-managed networking for libvirt";

      bridgeName = mkOption {

In order to try and understand what I was doing I then went searching for the relevant ‘command reference’. I started in Appendix A where it jumped from virtualisation.libvirtd.extraoptions to virtualisation.libvirtd.onBoot - skipping networking. I went and looked in libvirtd.nix but couldn’t find any reference there either.

I guess I therefore have the following questions;

  1. Is searching the manual, the wiki, and discourse the best way to find configuration examples?
  2. If I find examples on how to do something for Ubuntu, Fedora, Arch etc what is the path to working out how to translate this to a configuration in a .nix file?
  3. If I want to check syntax, options or indeed that a command is supported like “bridgeName = mkOption {” where is the right place to look?

Please forgive me if this is a poorly structured question or I have missed something very obvious, I am trying to learn so that I can be somewhat self-sufficient and perhaps even give back at some point. Many thanks

4 Likes
2

Great question, thank you for writing it out in detail!

First of all note that the example you linked declares a new NixOS module that does not exist anywhere else. There appears to be no usage examples of this module.

tl;dr: You will probably be able to make use of it by adding that file to the imports list in your NixOS configuration.

The NixOS Wiki on NixOS modules is a bit thin on explaining the difference between declaring options and defining configurations, and sadly it is often the only resource people manage to find. The authoritative source on NixOS modules is the (very unfortunately named) Writing NixOS Modules section in the NixOS manual.

Yes, and search.nixos.org/options (although the examples are usually per option).

There are two possibilities:

  1. The service or program you configure already has a NixOS module, which either shows how Nix attributes are mapped to the software’s settings or which has an attribute for custom settings as a string.
  2. There exists no NixOS module (as in your case) and you have to write your own, which can be a lot more involved (see https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules for instructions).

To check for existing configuration options, search.nixos.org/options is the best way.

Your input and help is highly appreciated, as expert Nix/Nixpkgs/NixOS users and contributors often don’t see the pain you’re going through (as theirs is in a distant past), and do not read the bulk of the documentation any more (because they don’t need to) to see why it may derail people.
Find here where and how you can contribute most easily, and check what the Nix documentation team is up to if you want to get in touch.

3 Likes
3

Thank you. I will work through your reply over the next two days but straight-away I can see that the NixOS Search is one of the tools I hadn’t seen. It was right in front of me :man_facepalming: but sometimes I just plain miss things. I’ve been using the search pages for packages regularly too!

I looked at that link multiple times and erroneously concluded it was ‘config’ based on the ip-addresses it contained. I look forward to understanding the difference between declaring and defining. Even though I have looked at multiple ‘.nix’ files, I’m not sure I had appreciated that they could be either even though again it was right in front of me.

Many Thanks

4

As the author of the satirical How to learn Nix said:

Don’t worry, you’re not dumb, this is just really confusing.

We’re working on improving the situation step by step, and it takes time. This is why you speaking up is so valuable, it makes all these issues more visible.

6 Likes