ALPHA: wire is a tool to deploy nixos systems
wire.althaea.zone/
althaea.zone
1---
2comment: true
3title: Deployment Keys Basics
4description: Deploy some basic secrets with wire tool.
5---
6
7# Deployment Keys Basics
8
9{{ $frontmatter.description }}
10
11## Creating a `secrets.nix`
12
13Lets create a NixOS module that will contain our secret keys, and import it:
14
15```nix:line-numbers [hive.nix]
16let
17 sources = import ./npins;
18 wire = import sources.wire;
19in
20wire.makeHive {
21 meta.nixpkgs = import sources.nixpkgs { };
22
23 virtual-machine = {
24 deployment.target = {
25 port = 2222;
26 hosts = [ "localhost" ];
27 };
28
29 imports = [
30 ./vm.nix
31 ./secrets.nix # [!code ++]
32 ];
33
34 environment.systemPackages = [ pkgs.vim ];
35
36 nixpkgs.hostPlatform = "x86_64-linux";
37 };
38}
39```
40
41```nix:line-numbers [secrets.nix]
42{
43 deployment.keys = {
44 # the key's unique name is `"basic.txt"`.
45 "basic.txt" = {
46 # In this key's case, the source is a literal string:
47 source = ''
48 Hello World
49 '';
50 };
51 };
52}
53```
54
55::: details
56Further details on the `deployment.keys` options can be found
57[in the reference](/reference/module.html#deployment-keys)
58:::
59
60Once we deploy this new configuration to the virtul machine,
61`/run/keys/basic.txt` will be created with the contents of the key.
62
63```sh
64[nix-shell]$ wire apply keys
65 WARN lib::nix_log: Store URL: ssh://root@localhost
66(root@localhost) Password:
67
68```
69
70```sh [Virtual Machine]
71[root@wire-tutorial:~]# cat /run/keys/basic.txt
72Hello World
73
74```
75
76You successfully deployed your first, albeit not-so-secret, secret key! Let's
77move on from literal-text keys and use something a bit more powerful.
78
79## File-sourced keys <Badge type="info">Optional</Badge>
80
81This section is optional to try, but you can also pass `deployment.keys.<name>.source`
82a file path. It's contents is read and treated as literal text.
83
84```sh
85$ echo hello world > very-important-secret.txt
86```
87
88```nix:line-numbers [secrets.nix]
89{
90 deployment.keys = {
91 # ...
92
93 "very-important-secret.txt" = { # [!code ++]
94 source = ./very-important-secret.txt; # [!code ++]
95 }; # [!code ++]
96 };
97}
98```
99
100```sh [Virtual Machine]
101[root@wire-tutorial:~]# cat /run/keys/very-important-secret.txt
102hello world
103
104```
105
106## Command-sourced keys
107
108Command-sourced keys are where the real power of wire keys lie. By passing a
109list of strings, wire will execute them as a command and create a key out of it's `stdout`.
110
111Because the command's output is never written to the nix store, these can be
112considered real secrets.
113
114To create a basic example, update your `secrets.nix` to include a secret that
115echos "hello world":
116
117```nix:line-numbers [secrets.nix]
118{
119 deployment.keys = {
120 # ...
121
122 "command.txt" = { # [!code ++]
123 source = [ # [!code ++]
124 "echo" # [!code ++]
125 "hello world" # [!code ++]
126 ]; # [!code ++]
127 }; # [!code ++]
128 };
129}
130```
131
132After a quick `wire deploy secrets`, the `/run/keys/command.txt` file is
133created:
134
135```sh [Virtual Machine]
136[root@wire-tutorial:~]# cat /run/keys/command.txt
137hello world
138
139```
140
141Hopefully you can see the potential of command-sourced keys, as these are the
142basic building block of how we achieve encrypted secrets with wire.