doc: Add system-manager manual mdBook (#206)
* doc: Add system-manager manual mdBook * Add basic nixos installation steps * Continue testing for nixos installation * Add more info regarding nix channel usage * Add some notes to self * Add README to manual * add ad-hoc section, and do some re-arranging * Add systemd service module example to introduction.md * wip usage * add selinux and minimal usage examples * add remaining manual sections
This commit is contained in:
[eureka@nixos]
GitHub
parent
fcc225c5aa
commit
1c2ce69f32
20 changed files with 795 additions and 9 deletions
|
|
@ -7,3 +7,7 @@ includes = ["*.nix"]
|
|||
[formatter.rustfmt]
|
||||
command = "rustfmt"
|
||||
includes = ["*.rs"]
|
||||
|
||||
[formatter.markdown]
|
||||
command = "mdformat"
|
||||
includes = ["*.md"]
|
||||
|
|
|
|||
18
README.md
18
README.md
|
|
@ -17,12 +17,10 @@
|
|||
|
||||
This project provides a basic method to manage system configuration using [Nix][nixos]
|
||||
on any Linux distribution.
|
||||
It builds on the many modules that already exist in [NixOS][nixos].
|
||||
It builds on the many [modules that already exist in NixOS](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules).
|
||||
|
||||
*Warning*: System Manager is a work in progress, you can expect things not to work or to break.
|
||||
|
||||
[nixos]: https://nixos.org
|
||||
|
||||
## Usage
|
||||
|
||||
### Install Nix
|
||||
|
|
@ -39,9 +37,6 @@ to install Nix.
|
|||
> for which one you want to install. System Manager is not tested against Determinate Nix.
|
||||
> It's recommended to use the official Nix if installing via the Determinate Nix Installer.
|
||||
|
||||
[official-installer]: https://nixos.org/download.html
|
||||
[detsys-installer]: https://github.com/DeterminateSystems/nix-installer
|
||||
|
||||
## Usage with flakes
|
||||
|
||||
### Defining the configuration
|
||||
|
|
@ -59,7 +54,7 @@ A basic Nix flake using System Manager would look something like this:
|
|||
};
|
||||
};
|
||||
|
||||
outputs = { self, flake-utils, nixpkgs, system-manager }: {
|
||||
outputs = { self, nixpkgs, system-manager }: {
|
||||
systemConfigs.default = system-manager.lib.makeSystemConfig {
|
||||
modules = [
|
||||
./modules
|
||||
|
|
@ -115,6 +110,7 @@ A simple System Manager module could look something like this:
|
|||
### Activating the configuration
|
||||
|
||||
Once the configuration is defined, you can activate it using the `system-manager` CLI:
|
||||
|
||||
```sh
|
||||
nix run 'github:numtide/system-manager' -- switch --flake '.'
|
||||
```
|
||||
|
|
@ -123,11 +119,11 @@ nix run 'github:numtide/system-manager' -- switch --flake '.'
|
|||
|
||||
By design flakes run in [pure evaluation mode](https://wiki.nixos.org/wiki/Flakes#Making_your_evaluations_pure).
|
||||
In some cases you may not want this. To run an impure evaluation of the flake, add the following option to your command:
|
||||
|
||||
```sh
|
||||
--nix-option pure-eval false
|
||||
```
|
||||
|
||||
|
||||
## Currently supported features
|
||||
|
||||
Currently it is possible to configure files under `/etc/` and systemd services.
|
||||
|
|
@ -145,7 +141,7 @@ System Manager is currently only supported on NixOS and Ubuntu. However, it can
|
|||
}
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> \[!WARNING\]
|
||||
> This is unsupported and untested. Use at your own risk.
|
||||
|
||||
## Commercial support
|
||||
|
|
@ -154,3 +150,7 @@ Looking for help or customization?
|
|||
|
||||
Get in touch with Numtide to get a quote. We make it easy for companies to
|
||||
work with Open Source projects: <https://numtide.com/contact>
|
||||
|
||||
[detsys-installer]: https://github.com/DeterminateSystems/nix-installer
|
||||
[nixos]: https://nixos.org
|
||||
[official-installer]: https://nixos.org/download.html
|
||||
|
|
|
|||
1
manual/.gitignore
vendored
Normal file
1
manual/.gitignore
vendored
Normal file
|
|
@ -0,0 +1 @@
|
|||
book
|
||||
7
manual/README.md
Normal file
7
manual/README.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# System Manager Manual
|
||||
|
||||
To get started, use the `shell.nix` devShell from the project root with either the `nix develop` or `nix-shell` commands.
|
||||
|
||||
This will put `mdbook` on your `$PATH`.
|
||||
|
||||
To view the book locally with live reloading, run `mdbook serve manual` from the project root.
|
||||
6
manual/book.toml
Normal file
6
manual/book.toml
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
[book]
|
||||
authors = ["numtide-contributors"]
|
||||
language = "en"
|
||||
multilingual = false
|
||||
src = "src"
|
||||
title = "System Manager Manual"
|
||||
22
manual/src/SUMMARY.md
Normal file
22
manual/src/SUMMARY.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Table of Contents
|
||||
|
||||
- [Table of Contents](./SUMMARY.md)
|
||||
- [Preface](./preface.md)
|
||||
- [Introduction](./introduction.md)
|
||||
- [Installation](./installation.md)
|
||||
- [Standalone Installation](./installation/standalone.md)
|
||||
- [NixOS](./installation/nixos.md)
|
||||
- [Usage](./usage.md)
|
||||
- [Example Configuration](./usage/example-configuration.md)
|
||||
- [Environment](./usage/environment.md)
|
||||
- [Systemd Services](./usage/systemd-services.md)
|
||||
- [Contributing](./contributing.md)
|
||||
- [Extending System Manager](./contributing/extending-system-manager.md)
|
||||
- [Troubleshooting](./troubleshooting.md)
|
||||
- [SELinux](./troubleshooting/selinux.md)
|
||||
|
||||
<!--
|
||||
TODO:
|
||||
- Building and deploying a configuration to remote machine
|
||||
- Docker guide
|
||||
-->
|
||||
36
manual/src/contributing.md
Normal file
36
manual/src/contributing.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Contributing
|
||||
|
||||
Welcome! Thank you for interest in the `system-manager` project, your contributions are greatly appreciated.
|
||||
|
||||
The following is a general guide for contributing to the project. For guidance on extending `system-manager` to fit specific needs,
|
||||
such as adding support for your distribution, or creating a release branch, see the [Extending System Manager](./contributing/extending-system-manager.md) section of the manual.
|
||||
|
||||
## Getting Started
|
||||
|
||||
> `system-manager` development requires a nix installation with the `flakes` and `nix-command` features enabled. If you do not have nix installed, please refer to the [Installation](./installation.md) section of the manual.
|
||||
|
||||
1. Firstly, [create a fork the repository](github.com/numtide/system-manager/fork) where you will make your changes.
|
||||
1. Create a copy of your newly created fork on your local machine: `git clone git@github.com:<USER>/system-manager.git`, where `<USER>` is which ever account the fork was created on.
|
||||
1. Enter the development environment: `nix develop`. This will supply you with the tool necessary to build and test the repository.
|
||||
1. [Create an issue](#creating-issues) for the problem you are trying to solve, if it does not already exist.
|
||||
1. [Create a pull request](#creating-pull-requests) that would close the issue.
|
||||
|
||||
### Creating Pull Requests
|
||||
|
||||
> Important: Please be sure an issue exists for the problem you are trying to fix before opening a pull request.
|
||||
|
||||
1. Create a working branch that targets the issue number you would like to close: `git checkout -b <USER>/123`.
|
||||
1. Add, commit and push your changes:
|
||||
|
||||
```sh
|
||||
git add -A
|
||||
git commit -m "fix: Fixes ..."
|
||||
git push origin <USER>/123
|
||||
```
|
||||
|
||||
3. [Open a pull request upstream](https://github.com/numtide/system-manager/compare) for your branch targetting the `main` branch.
|
||||
1. Please add a few sentences which describe your changes, and use [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) to close the issue your pull request aims to close automatically.
|
||||
|
||||
### Creating Issues
|
||||
|
||||
Before creating a new issue, please do a [quick search of the existing issues](github.com/numtide/system-manager/issues) to be sure the problem is not already being tracked or worked on by someone else.
|
||||
70
manual/src/contributing/extending-system-manager.md
Normal file
70
manual/src/contributing/extending-system-manager.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# Extending System Manager
|
||||
|
||||
## Creating an Ad-Hoc Release
|
||||
|
||||
There is currently not a release plan that follows nixpkgs releases, but the following ad-hoc solution is possible. The following guide is a walk-through of
|
||||
how to create a release branch for some version of nixpkgs, in this case `nixpkgs-24.05`, which the commit for can be found [here](https://github.com/numtide/system-manager/compare/numtide:64ca98a...numtide:d9cd850).
|
||||
|
||||
1. Check that a release branch for the required version does not already exist.
|
||||
1. Fork and clone the `system-manager` repository and create a new branch for the release in the following format `release-<TAG>`, for example:
|
||||
|
||||
```sh
|
||||
git checkout -b release-24.05
|
||||
```
|
||||
|
||||
3. Update the `nixpkgs` ref in the flake inputs with the new tag:
|
||||
|
||||
```diff
|
||||
# system-manager/flake.nix
|
||||
{
|
||||
- inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
+ inputs.nixpkgs.url = "github:NixOS/nixpkgs/24.05";
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
4. Run `nix flake update nixpkgs`.
|
||||
1. Update the `Cargo.toml` package with the appropriate versioning information. The `version` attribute should include the `nixpkgs` tag,
|
||||
and the `rust-version` should be locked at the version of rust which will make the flake checks compile successfully. For `nixpkgs-24.05` that looks like:
|
||||
|
||||
```diff
|
||||
# Cargo.toml
|
||||
[package]
|
||||
name = "system_manager"
|
||||
- version = "0.1.0"
|
||||
+ version = "0.1.0+nixpkgs-24.05"
|
||||
+ rust-version = "1.77"
|
||||
```
|
||||
|
||||
6. Run `cargo generate-lockfile`.
|
||||
1. Ensure the flake checks pass: `nix flake check --keep-going -L`.
|
||||
|
||||
> Note that there may be breaking changes between nixpkgs versions which could require additional debugging.
|
||||
|
||||
8. Lastly, reference the release branch in your flake:
|
||||
|
||||
```diff
|
||||
# your-flake.nix
|
||||
{
|
||||
- inputs.nixpkgs.url = "github:NixOS/nixpkgs/23.11";
|
||||
+ inputs.nixpkgs.url = "github:NixOS/nixpkgs/24.05";
|
||||
inputs.system-manager = {
|
||||
- url = "github:numtide/system-manager";
|
||||
+ type = "github";
|
||||
+ owner = "numtide";
|
||||
+ repo = "system-manager";
|
||||
+ ref = "release-24.05";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Adding New Distributions
|
||||
|
||||
> This section assumes you have an existing nix installation. Otherwise, refer to the [Installation](../installation.md) section of the manual for installation instructions.
|
||||
|
||||
To add a new distribution, first initialize a new flake repository with `nix run 'github:numtide/system-manager' -- init --flake --allow-any-distro`.
|
||||
Once the flake is initialized, switch to the new configuration with `nix run 'github:numtide/system-manager' -- switch --flake '.'`. It is not unlikely
|
||||
that this will produce errors, but please refer to the FAQ, github issues, discussion or contributing guide for potential solutions, or instructions for upstreaming changes.
|
||||
|
||||
Once the distribution is stable, it can be added to the `supportedIds` list that is part of the [system-manager module](../../../nix/modules/default.nix)'s `config` attribute.
|
||||
41
manual/src/installation.md
Normal file
41
manual/src/installation.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Installation
|
||||
|
||||
## Supported Systems
|
||||
|
||||
System Manager is in the early stages of development and while it aims to support any Linux
|
||||
distribution, currently official support is limited to the following distributions:
|
||||
|
||||
- Ubuntu
|
||||
- NixOS
|
||||
|
||||
> We would love to expand this list! Please see our [Contributing Guide](./contributing.md)
|
||||
> for instructions on how to contribute to `system-manager`.
|
||||
|
||||
## [NixOS Installation](./installation/nixos.md)
|
||||
|
||||
NixOS is a fully reproducible and immutable Linux distribution based on the Nix package manager that uses an atomic update model.
|
||||
|
||||
To install System Manager on NixOS, see [NixOS Installation](./installation/nixos.md).
|
||||
|
||||
## Other Distributions
|
||||
|
||||
### Install Nix
|
||||
|
||||
In order to use System Manager, you will first need to install Nix.
|
||||
You can either use your distro's package manager, or use one of the available options
|
||||
to install Nix.
|
||||
|
||||
- [Official Nix Installer][official-installer] - The canonical source for installing nix.
|
||||
- [Determinate Nix Installer][detsys-installer] - A wrapper around the official installer that has SELinux support, and enables flake features by default.
|
||||
|
||||
> Note: Be advised that the Determinate Systems installer has the option for the official
|
||||
> Nix, as well as Determinate's own variant of Nix (Determinate Nix). It will prompt you
|
||||
> for which one you want to install. System Manager is not tested against Determinate Nix.
|
||||
> It's recommended to use the official Nix if installing via the Determinate Nix Installer.
|
||||
|
||||
### [Install System Manager](./installation/standalone.md)
|
||||
|
||||
To install System Manager, please find the instructions for your preferred distribution at [Standalone Installation](./installation/standalone.md).
|
||||
|
||||
[detsys-installer]: https://github.com/DeterminateSystems/nix-installer
|
||||
[official-installer]: https://nixos.org/download.html
|
||||
146
manual/src/installation/nixos.md
Normal file
146
manual/src/installation/nixos.md
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
# NixOS Installation
|
||||
|
||||
This section covers how to get `system-manager`, the command line application, on your system.
|
||||
Please refer to [Usage](./usage.md) for how to handle creation and application of modules, and management of files.
|
||||
|
||||
## Flake Based Configurations
|
||||
|
||||
To add `system-manager` to an existing flake based configuration, add the following to the `inputs` field of `flake.nix`.
|
||||
|
||||
```nix
|
||||
# flake.nix
|
||||
{
|
||||
inputs = {
|
||||
system-manager.url = "github:numtide/system-manager";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
<!--
|
||||
@channels
|
||||
Remove after #207 is completed.
|
||||
-->
|
||||
|
||||
> NOTE: Occassionally the nixpkgs version may be incompatible with the `main` branch of `system-manager`.
|
||||
> In such cases, check the current version of nixpkgs in `flake.lock` against `system-manager`.
|
||||
> You may need to update the version of nixpkgs in `inputs`, or find the commit at which `system-manager` is supported
|
||||
> at that version of nixpkgs and lock `system-manager` at that commit. For instance, the following commit is the only commit
|
||||
> that will work for (at least) `nixpkgs-24.05` and below due to changes in Cargo's lock file parsing standard after Rust 1.83
|
||||
> became available in nixpkgs:
|
||||
>
|
||||
> ```nix
|
||||
> {
|
||||
> inputs = {
|
||||
> nixpkgs.url = "github:NixOS/nixpkgs/24.05";
|
||||
> system-manager = {
|
||||
> type = "github";
|
||||
> owner = "numtide";
|
||||
> repo = "system-manager";
|
||||
> ref = "64627568a52fd5f4d24ecb504cb33a51ffec086d";
|
||||
> };
|
||||
> };
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> See [Issue #207](https://github.com/numtide/system-manager/issues/207) for progress on alleviating this problem, or [create an ad-hoc release](../contributing/extending-system-manager.md).
|
||||
|
||||
The `system-manager` package is available via the flake's `packages` attribute.
|
||||
The following is a flake that declares a single NixOS configuration containing a module with the `system-manager`
|
||||
package added to the environment.
|
||||
|
||||
```nix
|
||||
# flake.nix
|
||||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
system-manager = {
|
||||
url = "github:numtide/system-manager";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
};
|
||||
outputs = inputs@{ self }: {
|
||||
let
|
||||
system = "aarch64-linux";
|
||||
host = "nixos";
|
||||
in
|
||||
nixosConfigurations.${host} = inputs.nixpkgs.lib.nixosSystem {
|
||||
inherit system;
|
||||
modules = [
|
||||
({ config, ... }: {
|
||||
environment.systemPackages = [
|
||||
inputs.system-manager.packages.${system}.system-manager
|
||||
];
|
||||
})
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Switching to this configuration will install `system-manager`.
|
||||
|
||||
```sh
|
||||
sudo nixos-rebuild switch --flake ./path/to/flake.nix#nixos
|
||||
system-manager --version
|
||||
# system_manager 0.1.0
|
||||
```
|
||||
|
||||
> Note: In this case our host's name is `nixos`, and to reference an attribute we tack on `#` to the flake path, followed by the name of the attribute we want to reference.
|
||||
|
||||
## Nix Channels
|
||||
|
||||
> _**NOTICE**_: The `system-manager` application currently only supports flakes. Until a release schedule is put in place that can support nix channels, it is advised to follow the guide for [flake based configurations](#flake-based-configurations) instead.
|
||||
> If an ad-hoc release is necessary, see [Creating an Ad-Hoc Release](../contributing/extending-system-manager.md).
|
||||
|
||||
<!-- This is the NixOS experience without the flake features enabled. You can find which channels you are currently using with `nix-channel --list`. -->
|
||||
|
||||
<!-- The configuration that NixOS uses with channels is at `/etc/nixos/configuration.nix`. -->
|
||||
|
||||
<!--
|
||||
@channels
|
||||
Remove after #207 is completed.
|
||||
-->
|
||||
|
||||
<!-- Currently, there isn't a release plan for `system-manager` that is in tandem with nixpkgs releases. This has been an issue -->
|
||||
|
||||
<!-- in some cases that have caused failures in [_version mismatches_](https://github.com/numtide/system-manager/issues/172). -->
|
||||
|
||||
<!-- The only available archive is the `main` branch, which is pinned to `nixos-unstable`. -->
|
||||
|
||||
<!-- If you are currently using the unstable channel already and wish to use channels specifically you could do the following: -->
|
||||
|
||||
<!-- ```sh -->
|
||||
|
||||
<!-- nix-channel --add https://github.com/numtide/system-manager/archive/main.tar.gz system-manager -->
|
||||
|
||||
<!-- nix-channel --update -->
|
||||
|
||||
<!-- nix-channel --list -->
|
||||
|
||||
<!-- # system-manager https://github.com/numtide/system-manager/archive/main.tar.gz -->
|
||||
|
||||
<!-- ``` -->
|
||||
|
||||
<!-- TODO: Test this, as I am just speculating that this is possible. -->
|
||||
|
||||
<!-- It should then be possible to add the following to `imports` in `/etc/nixos/configuration.nix` and gain access to the [`system-manager` module](../../../nix/modules/default.nix)'s `options` attribute: -->
|
||||
|
||||
<!-- ```nix -->
|
||||
|
||||
<!-- { pkgs, ... }: { -->
|
||||
|
||||
<!-- imports = [ -->
|
||||
|
||||
<!-- ``` -->
|
||||
|
||||
<!-- <system-manager/nix/modules> -->
|
||||
|
||||
<!-- ./hardware-configuration.nix -->
|
||||
|
||||
<!-- ``` -->
|
||||
|
||||
<!-- ]; -->
|
||||
|
||||
<!-- } -->
|
||||
|
||||
<!-- ``` -->
|
||||
139
manual/src/installation/standalone.md
Normal file
139
manual/src/installation/standalone.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
# Standalone Installation
|
||||
|
||||
This section covers how to get `system-manager`, the command line application, on your system.
|
||||
Please refer to [Usage](./usage.md) for how to handle creation and application of modules, and management of files.
|
||||
|
||||
## Flake Based Configurations
|
||||
|
||||
To add `system-manager` to an existing flake based configuration, add the following to the `inputs` field of `flake.nix`.
|
||||
|
||||
```nix
|
||||
# flake.nix
|
||||
{
|
||||
inputs = {
|
||||
system-manager.url = "github:numtide/system-manager";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
<!--
|
||||
@channels
|
||||
Remove after #207 is completed.
|
||||
-->
|
||||
|
||||
> NOTE: Occassionally the nixpkgs version may be incompatible with the `main` branch of `system-manager`.
|
||||
> In such cases, check the current version of nixpkgs in `flake.lock` against `system-manager`.
|
||||
> You may need to update the version of nixpkgs in `inputs`, or find the commit at which `system-manager` is supported
|
||||
> at that version of nixpkgs and lock `system-manager` at that commit. For instance, the following commit is the only commit
|
||||
> that will work for (at least) `nixpkgs-24.05` and below due to changes in Cargo's lock file parsing standard after Rust 1.83
|
||||
> became available in nixpkgs:
|
||||
>
|
||||
> ```nix
|
||||
> {
|
||||
> inputs = {
|
||||
> nixpkgs.url = "github:NixOS/nixpkgs/24.05";
|
||||
> system-manager = {
|
||||
> type = "github";
|
||||
> owner = "numtide";
|
||||
> repo = "system-manager";
|
||||
> ref = "64627568a52fd5f4d24ecb504cb33a51ffec086d";
|
||||
> };
|
||||
> };
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> See [Issue #207](https://github.com/numtide/system-manager/issues/207) for progress on alleviating this problem, or [create an ad-hoc release](../contributing/extending-system-manager.md).
|
||||
|
||||
The `system-manager` package is available via the flake's `packages` attribute.
|
||||
The following is a flake that declares a single system configuration containing a module with the `system-manager`
|
||||
package added to the environment.
|
||||
|
||||
```nix
|
||||
# flake.nix
|
||||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
system-manager = {
|
||||
url = "github:numtide/system-manager";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
};
|
||||
outputs = inputs@{ self }: {
|
||||
systemConfigs.ubuntu = inputs.system-manager.lib.makeSystemConfig {
|
||||
modules = [
|
||||
({
|
||||
config.environment.systemPackages = [
|
||||
inputs.system-manager.packages.${system}.system-manager
|
||||
];
|
||||
})
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Switching to this configuration will install `system-manager`.
|
||||
|
||||
Ensure that `$PATH` state is used when invoking nix via `sudo`, which is required for switching configurations.
|
||||
|
||||
```sh
|
||||
sudo env PATH="$PATH" nix run 'github:numtide/system-manager' -- switch --flake '.#ubuntu'
|
||||
system-manager --version
|
||||
# system_manager 0.1.0
|
||||
```
|
||||
|
||||
> Note: In this case our host's name is `ubuntu`, and to reference an attribute we tack on `#` to the flake path, followed by the name of the attribute we want to reference.
|
||||
|
||||
## Nix Channels
|
||||
|
||||
> _**NOTICE**_: The `system-manager` application currently only supports flakes. Until a release schedule is put in place that can support nix channels, it is advised to follow the guide for [flake based configurations](#flake-based-configurations) instead.
|
||||
> If an ad-hoc release is necessary, see [Creating an Ad-Hoc Release](../contributing/extending-system-manager.md).
|
||||
|
||||
<!-- This is the Nix experience without the flake features enabled. You can find which channels you are currently using with `nix-channel --list`. -->
|
||||
|
||||
<!--
|
||||
@channels
|
||||
Remove after #207 is completed.
|
||||
-->
|
||||
|
||||
<!-- Currently, there isn't a release plan for `system-manager` that is in tandem with nixpkgs releases. This has been an issue -->
|
||||
|
||||
<!-- in some cases that have caused failures in [_version mismatches_](https://github.com/numtide/system-manager/issues/172). -->
|
||||
|
||||
<!-- The only available archive is the `main` branch, which is pinned to `nixos-unstable`. -->
|
||||
|
||||
<!-- If you are currently using the unstable channel already and wish to use channels specifically you could do the following: -->
|
||||
|
||||
<!-- ```sh -->
|
||||
|
||||
<!-- nix-channel --add https://github.com/numtide/system-manager/archive/main.tar.gz system-manager -->
|
||||
|
||||
<!-- nix-channel --update -->
|
||||
|
||||
<!-- nix-channel --list -->
|
||||
|
||||
<!-- # system-manager https://github.com/numtide/system-manager/archive/main.tar.gz -->
|
||||
|
||||
<!-- ``` -->
|
||||
|
||||
<!-- TODO: Test this, as I am just speculating that this is possible. -->
|
||||
|
||||
<!-- It should then be possible to add the following to `imports` in `~/.config/system-manager/system.nix` and gain access to the [`system-manager` module](../../../nix/modules/default.nix)'s `options` attribute: -->
|
||||
|
||||
<!-- ```nix -->
|
||||
|
||||
<!-- { pkgs, ... }: { -->
|
||||
|
||||
<!-- imports = [ -->
|
||||
|
||||
<!-- ``` -->
|
||||
|
||||
<!-- <system-manager/nix/modules> -->
|
||||
|
||||
<!-- ``` -->
|
||||
|
||||
<!-- ]; -->
|
||||
|
||||
<!-- } -->
|
||||
|
||||
<!-- ``` -->
|
||||
61
manual/src/introduction.md
Normal file
61
manual/src/introduction.md
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
# Introduction
|
||||
|
||||
`system-manager` is a command line tool that uses system configurations written in the nix language
|
||||
to manage installation of system services on Linux distributions, such as Ubuntu, in a similar manner to
|
||||
`nixos-rebuild` on NixOS systems.
|
||||
|
||||
## Hello, System Manager
|
||||
|
||||
The following snippet of nix code...
|
||||
|
||||
```nix
|
||||
{ lib, pkgs, ... }:
|
||||
{
|
||||
config.systemd.services.say-hello = {
|
||||
description = "say-hello";
|
||||
enable = true;
|
||||
wantedBy = [ "system-manager.target" ];
|
||||
serviceConfig = {
|
||||
Type = "oneshot";
|
||||
RemainAfterExit = true;
|
||||
};
|
||||
script = ''
|
||||
${lib.getBin pkgs.hello}/bin/hello
|
||||
'';
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
produces a systemd service file, `/etc/systemd/system/say-hello.service`:
|
||||
|
||||
```service
|
||||
[Unit]
|
||||
Description=say-hello
|
||||
|
||||
[Service]
|
||||
Environment="PATH=..."
|
||||
ExecStart=/nix/store/...-unit-script-say-hello-start/bin/say-hello-start
|
||||
RemainAfterExit=true
|
||||
Type=oneshot
|
||||
|
||||
[Install]
|
||||
WantedBy=system-manager.target
|
||||
```
|
||||
|
||||
When the service is enabled it results in `"Hello, World!"` in the journal of the service `say-hello.service`:
|
||||
|
||||
```sh
|
||||
systemctl status say-hello.service
|
||||
● say-hello.service - say-hello
|
||||
Loaded: loaded (/etc/systemd/system/say-hello.service; enabled; vendor preset: enabled)
|
||||
Active: active (exited) since Wed 2025-05-21 09:39:24 PDT; 11min ago
|
||||
Main PID: 41644 (code=exited, status=0/SUCCESS)
|
||||
CPU: 3ms
|
||||
|
||||
May 21 09:39:24 ubuntu systemd[1]: Starting say-hello...
|
||||
May 21 09:39:24 ubuntu say-hello-start[41646]: Hello, world!
|
||||
May 21 09:39:24 ubuntu systemd[1]: Finished say-hello.
|
||||
```
|
||||
|
||||
> Context omitted for clarity, see [Example Configuration](./usage/example-configuration.md)
|
||||
> for a fully functioning use case.
|
||||
6
manual/src/preface.md
Normal file
6
manual/src/preface.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Preface
|
||||
|
||||
This manual contains information on how to install, use and extend `system-manager`.
|
||||
|
||||
For questions, please have a look at the discussion board prior to opening a new ticket.
|
||||
If you run into a bug or would like to request a feature that is not yet tracked, please [open an issue](https://github.com/numtide/system-manager/issues).
|
||||
3
manual/src/troubleshooting.md
Normal file
3
manual/src/troubleshooting.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Troubleshooting
|
||||
|
||||
The following section contains steps to solve common issues. If there is an issue not listed here, please [open an issue](./contributing.md).
|
||||
6
manual/src/troubleshooting/selinux.md
Normal file
6
manual/src/troubleshooting/selinux.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# SELinux
|
||||
|
||||
Currently, `system-manager` does not work with SELinux, but we are working on it! For a trail to follow please see [this issue](https://github.com/numtide/system-manager/issues/115).
|
||||
|
||||
The Determinate Systems installer automatically creates a policy for nix itself. Please see the [Installation](../installation.md) section for details.
|
||||
This alone will not be enough for `system-manager` to work, but it's a step in the right direction. As of now, the only way for it to work is to set the policy to permissive.
|
||||
12
manual/src/usage.md
Normal file
12
manual/src/usage.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Usage
|
||||
|
||||
The [`system-manager` nix module](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix) currently supports the following `options`:
|
||||
|
||||
- management of [`systemd` service modules](./usage/systemd-services.md)
|
||||
- management of [system level packages](./usage/environment.md)
|
||||
- management of [files and permissions](./usage/environment.md)
|
||||
|
||||
> **Note**: Docs can fall out of date. Please refer to the [module itself](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix) for an exhaustive look at what is supported.
|
||||
|
||||
If an option you would like to see is not currently supported, please consider [contributing
|
||||
to the project](./contributing.md), or open an issue and a maintainer may add support if time allows.
|
||||
46
manual/src/usage/environment.md
Normal file
46
manual/src/usage/environment.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# Managing System Environment
|
||||
|
||||
## Adding Packages
|
||||
|
||||
Adding packages with `system-manager` works in the same way that it does on `nixos`, the only difference is that the `system-manager` module expects a `config`.
|
||||
The list of available config options can be found [here](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix).
|
||||
|
||||
Below is a minimal example `system.nix` which can be imported in via `modules` with `makeSystemConfig`.
|
||||
|
||||
```nix
|
||||
# system.nix
|
||||
{ pkgs, ... }:
|
||||
{
|
||||
config = {
|
||||
environment.systemPackages = with pkgs; [
|
||||
cowsay
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Managing Files
|
||||
|
||||
Managing files in `/etc` with `system-manager` works in the same way that it does on `nixos`, the only difference is that the `system-manager` module expects a `config`.
|
||||
The list of available config options can be found [here](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix).
|
||||
|
||||
Below is a minimal example `system.nix` which can be imported in via `modules` with `makeSystemConfig`.
|
||||
|
||||
```nix
|
||||
# system.nix
|
||||
{ ... }:
|
||||
{
|
||||
config = {
|
||||
environment.etc = {
|
||||
with_ownership = {
|
||||
text = ''
|
||||
...
|
||||
'';
|
||||
mode = "0755";
|
||||
uid = 5;
|
||||
gid = 6;
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
137
manual/src/usage/example-configuration.md
Normal file
137
manual/src/usage/example-configuration.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
# Example Configuration
|
||||
|
||||
This is a minimal example which adds the `system-manager` package to the environment, a simple
|
||||
`say-hello` systemd service, and some arbitrary text file to `/etc`. Other examples used in testing
|
||||
can be found in the repository's [examples](https://github.com/numtide/system-manager/tree/main/examples) directory.
|
||||
|
||||
First, we create a `system.nix` module, which will be the base configuration for our system.
|
||||
|
||||
```nix
|
||||
{ lib, pkgs, ... }:
|
||||
{
|
||||
config = {
|
||||
nixpkgs.hostPlatform = "aarch64-linux";
|
||||
|
||||
environment = {
|
||||
# Packages that should be installed
|
||||
# on a system
|
||||
systemPackages = with pkgs; [
|
||||
git
|
||||
nil
|
||||
helix
|
||||
];
|
||||
|
||||
# Add directories and files to `/etc`
|
||||
# and set their permissions
|
||||
etc = {
|
||||
my_text_file = {
|
||||
text = ''
|
||||
Arbitrary text file content.
|
||||
'';
|
||||
};
|
||||
};
|
||||
};
|
||||
|
||||
# Create systemd services
|
||||
systemd.services.say-hello = {
|
||||
description = "say-hello";
|
||||
enable = true;
|
||||
wantedBy = [ "system-manager.target" ];
|
||||
serviceConfig = {
|
||||
Type = "oneshot";
|
||||
RemainAfterExit = true;
|
||||
};
|
||||
script = ''
|
||||
${lib.getBin pkgs.hello}/bin/hello
|
||||
'';
|
||||
};
|
||||
|
||||
# Configure systemd services
|
||||
services.say-hello.enable = true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Then we can reference the file path in our flake. For simplicity's sake, we include another
|
||||
attribute set in `modules` which captures the `system-manager` package as part of the system's
|
||||
`environment.systemPackages`.
|
||||
|
||||
> Because nix is a functional configuration language, this is cumulative
|
||||
> and the resulting system will include both the `systemPackages` from our `system.nix` as well as
|
||||
> any other modules we include which refer to `environment.systemPackages`.
|
||||
|
||||
```nix
|
||||
{
|
||||
description = "Example System Manager configuration.";
|
||||
|
||||
inputs = {
|
||||
# Specify the source of System Manager and Nixpkgs.
|
||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||
system-manager = {
|
||||
url = "github:numtide/system-manager";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
};
|
||||
|
||||
outputs =
|
||||
{
|
||||
self,
|
||||
nixpkgs,
|
||||
system-manager,
|
||||
...
|
||||
}:
|
||||
{
|
||||
systemConfigs.default = system-manager.lib.makeSystemConfig {
|
||||
# Specify your system configuration modules here, for example,
|
||||
# the path to your `system.nix`.
|
||||
modules = [
|
||||
./system.nix
|
||||
({
|
||||
config.environment.systemPackages = [
|
||||
system-manager.packages.${system}.system-manager
|
||||
];
|
||||
})
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Now that we have a system configuration that `system-manager` can build, we build and switch
|
||||
to the configuration in one step:
|
||||
|
||||
Ensure that `$PATH` state is used when invoking nix via `sudo`, which is required for switching configurations.
|
||||
|
||||
```sh
|
||||
sudo env PATH="$PATH" nix run 'github:numtide/system-manager' -- switch --flake '.#ubuntu'
|
||||
```
|
||||
|
||||
Once the command finishes, the following commands should yeild their expected output:
|
||||
|
||||
```sh
|
||||
system-manager --version
|
||||
system-manager 0.1.0
|
||||
|
||||
git --version
|
||||
git 2.49.0
|
||||
|
||||
nil --version
|
||||
nil 2024-08-06
|
||||
|
||||
hx --version
|
||||
helix 25.01.1 (e7ac2fcd)
|
||||
|
||||
cat /etc/my_text_file
|
||||
Arbitrary text file content.
|
||||
|
||||
systemctl status say-hello.service
|
||||
● say-hello.service - say-hello
|
||||
Loaded: loaded (/etc/systemd/system/say-hello.service; enabled; vendor preset: enabled)
|
||||
Active: active (exited) since Wed 2025-05-21 09:39:24 PDT; 11min ago
|
||||
Main PID: 41644 (code=exited, status=0/SUCCESS)
|
||||
CPU: 3ms
|
||||
|
||||
May 21 09:39:24 ubuntu systemd[1]: Starting say-hello...
|
||||
May 21 09:39:24 ubuntu say-hello-start[41646]: Hello, world!
|
||||
May 21 09:39:24 ubuntu systemd[1]: Finished say-hello.
|
||||
```
|
||||
41
manual/src/usage/systemd-services.md
Normal file
41
manual/src/usage/systemd-services.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Managing Systemd Service Modules
|
||||
|
||||
Custom or existing systemd services can be created and configured with `system-manager`.
|
||||
This topic is relative to `system-manager`, and is more directly correlated with `systemd`
|
||||
and `nix`. Since it requires knowledge of both we cover it minimally here, however, the
|
||||
following resources are a better reference for creating services with nix which can be
|
||||
used by the `system-manager` module.
|
||||
|
||||
- [Official `systemd.service` docs](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html)
|
||||
- [Systemd NixOS Wiki](https://wiki.nixos.org/wiki/Systemd)
|
||||
- [Search Engine for NixOS configuration options](https://mynixos.com/search?q=systemd) -- helpful for quickly finding attribute bindings for systemd
|
||||
|
||||
## Example systemd module
|
||||
|
||||
The following is a simple systemd timer which continues to capture timestamps into a log file
|
||||
once every minute, after the timer unit itself is activated.
|
||||
|
||||
Further configurations settings for creating a `systemd.timer` can be found in the [official `systemd.timer` docs](https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html).
|
||||
|
||||
```nix
|
||||
{ pkgs, ... }:
|
||||
{
|
||||
systemd = {
|
||||
timers.simple-timer = {
|
||||
wantedBy = [ "timers.target" ];
|
||||
timerConfig = {
|
||||
OnActiveSec = "10"; # Defines a timer relative to the moment the timer unit itself is activated.
|
||||
OnCalendar = "minutely";
|
||||
Unit = "simple-timer.service";
|
||||
Persistent = true; # Stores the last activated time to disk.
|
||||
};
|
||||
};
|
||||
services.simple-timer = {
|
||||
serviceConfig.Type = "oneshot";
|
||||
script = ''
|
||||
echo "Time: $(date)." >> /tmp/simple-timer.log
|
||||
'';
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
|
@ -38,5 +38,7 @@ pkgs.mkShellNoCC {
|
|||
nixfmt-rfc-style
|
||||
rustfmt
|
||||
clippy
|
||||
mdbook
|
||||
mdformat
|
||||
];
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue