ryan
/
wirenix
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fixes to docs

Browse Source
release
Matthew Salerno 1 year ago
parent eb9c2ec79f
commit b02749616e
1 changed files with 77 additions and 80 deletions
Show Stats Download Patch File Download Diff File

157
README.md
Unescape Escape View File

@ -2,26 +2,26 @@ WireNix is a Nix Flake designed to make creation of Wireguard mesh networks
easier. The simplist and most likely layout is a full mesh network, but Wirenix easier. The simplist and most likely layout is a full mesh network, but Wirenix
can also support arbitrary graph topologies. can also support arbitrary graph topologies.
# Reading the README # Reading the README
Due to Nix's dynamic typing, I have opted to define all my ACL configurations Due to Nix's dynamic typing, I have opted to define configurations in
in psuedo-typescript to make options more legible. I have chosen typescript psuedo-typescript to make options more legible. I have chosen typescript
because it looks somewhat like JSON and is easy to understand. Examples will because it looks somewhat like JSON and is easy to understand. Examples will
still be given in Nix EL. Function signatures will still follow the traditional still be given in Nix EL.
Haskell-like function signatures seen throughout nix projects.
You can start by reading the [ACL Configuration](ACL Configuration) section, You can start by reading the [[ACL Configuration]] section, then reading
then reading [Quick Start](Quick Start) section for how to configure your [[Quick Start]] section for how to configure your machines. Other sections
machines. Other sections exist to provide helpful context and advanced usage, exist to provide helpful context and advanced usage, but should not be
but should not be necessary for a working setup. necessary for a working setup.
Wirenix assumes a flakes setup, that's what I use. Maybe it works without Wirenix assumes a flakes setup, that's what I use. Maybe it works without
flakes, maybe not. I'm not familiar enough with the non-flakes landscape flakes, maybe not. I'm not familiar enough with the non-flakes landscape
to provide support. I am open to making simple changes to make using this to provide support. I am open to making simple changes to make using this
project without flakes easier if anyone has suggestions or wants to submit project work without flakes if anyone has suggestions or wants to submit
a patch. a patch.
# ACL Configuration # ACL Configuration
The ACL is a nix attrset designed to be represented in JSON for easy importing The ACL is a nix attrset designed to be represented in JSON for easy importing
and potential use outside of the nix ecosystem. and potential use outside of the nix ecosystem. The vast majority of all your
wirenix configuration will end up in here, with a few exceptions noted later.
## top level acl: ## top level acl:
```typescript ```typescript
@ -31,7 +31,7 @@ type ACL = {
groups: group[]; groups: group[];
peers: peer[]; peers: peer[];
connections: connection[]; connections: connection[];
extraArgs?: any; // goes to intermediate config extraArgs?: attrset; // goes to intermediate config
}; };
``` ```
@ -39,14 +39,15 @@ type ACL = {
older. At the moment there is only "v1" builtin. older. At the moment there is only "v1" builtin.
`extraArgs` is explained later, and can be ignored unless you are trying to `extraArgs` is explained later, and can be ignored unless you are trying to
make your own integrations. make your own integrations.
## subnet: ## subnet:
```typescript ```typescript
type subnet = { type subnet = {
name: str; name: str;
endpoints?: endpoint[]; endpoints?: endpoint[];
extraArgs?: any; // goes to intermediate config subnet presharedKeyFile?: str;
extraArgs?: attrset; // goes to intermediate config subnet
}; };
``` ```
@ -55,7 +56,7 @@ type subnet = {
type group = { type group = {
name: str; name: str;
endpoints?: endpoint[]; endpoints?: endpoint[];
extraArgs?: any; // goes to intermediate config group extraArgs?: attrset; // goes to intermediate config group
}; };
``` ```
@ -66,19 +67,19 @@ type peer = {
subnets: [subnetName: str]: { subnets: [subnetName: str]: {
listenPort: int; listenPort: int;
ipAddresses?: str[]; ipAddresses?: str[];
extraArgs?: any; // goes to intermediate config subnetConnection extraArgs?: attrset; // goes to intermediate config subnetConnection
}; };
publicKey: str; publicKey: str;
privateKeyFile: str; privateKeyFile: str;
groups?: str[]; groups?: str[];
endpoints?: endpoint[]; endpoints?: endpoint[];
extraArgs?: any; // goes to intermediate config peer extraArgs?: attrset; // goes to intermediate config peer
}; };
``` ```
`[subnetName: str]: {...}` means `subnets` is an object (attrset) with "`[subnetName: str]: {...}`" means "`subnets`" is an attrset with
string typed keys, and values that follows the typing of the nested object string typed keys, and values that follow the typing of the nested object
`...`. "`...`".
## Connection: ## Connection:
```typescript ```typescript
@ -86,7 +87,7 @@ type connection = {
a: filter; a: filter;
b: filter; b: filter;
subnets: str[]; subnets: str[];
extraArgs?: any; // merged into intermediate config peerConnection extraArgs?: attrset; // merged into intermediate config peerConnection
}; };
``` ```
@ -106,7 +107,7 @@ type endpoint = {
persistentKeepalive?: int; persistentKeepalive?: int;
dynamicEndpointRefreshSeconds?: int; dynamicEndpointRefreshSeconds?: int;
dynamicEndpointRefreshRestartSeconds?: int; dynamicEndpointRefreshRestartSeconds?: int;
extraArgs?: any; // merged to intermediate config peerConnection.endpoin extraArgs?: attrset; // merged to intermediate config peerConnection.endpoin
}; };
``` ```
@ -154,43 +155,44 @@ pass data into user defined Configuration Modules. Most users can ignore
1. Make your ACL according to the [ACL Configuration]](ACL Configuration) section. 1. Make your ACL according to the [ACL Configuration]](ACL Configuration) section.
You can look in the `examples/acl` folder for examples. You can look in the `examples/acl` folder for examples.
2. Include the module in your flake config: 2. Include the module in your flake config:
```nix ```nix
... ...
inputs.wirenix.url = "sourcehut:~msalerno/wirenix"; inputs.wirenix.url = "sourcehut:~msalerno/wirenix";
outputs = { self, nixpkgs, wirenix }: { outputs = { self, nixpkgs, wirenix }: {
nixosConfigurations = { nixosConfigurations = {
example = nixpkgs.lib.nixosSystem rec { example = nixpkgs.lib.nixosSystem rec {
system = "x86_64-linux"; system = "x86_64-linux";
modules = [ modules = [
./machines/example.nix ./machines/example.nix
wirenix.nixosModules.default wirenix.nixosModules.default
] ]
};
}; };
}; ```
```
3. Configure wirenix in your nixosConfiguration (`./machines/example.nix` in this 3. Configure wirenix in your nixosConfiguration (`./machines/example.nix` in this
case): case):
```nix ```nix
wirenix = { wirenix = {
enable = true; enable = true;
peerName = "example" # defaults to hostname otherwise peerName = "example" # defaults to hostname otherwise
configurer = "static" # defaults to "static", could also be "networkd" configurer = "static" # defaults to "static", could also be "networkd"
keyProviders = ["acl"]; # could also be ["agenix-rekey"] or ["acl" "agenix-rekey"] keyProviders = ["acl"]; # could also be ["agenix-rekey"] or ["acl" "agenix-rekey"]
# secretsDir = ../../secrets; # only if you're using agenix-rekey # secretsDir = ../../secrets; # only if you're using agenix-rekey
aclConfig = import ../../acl.nix; aclConfig = import ../../acl.nix;
}; };
``` ```
4. Profit 4. Profit
# Architecture # Architecture
WireNix consists of 5 main components: WireNix consists of 5 main components:
1. The shared ACL Configuration 1. The shared ACL Configuration
2. The Key Providers 2. Parser Modules
3. Parser Modules 3. The intermediate Configuration
4. The intermediate Configuration 4. Configuration Modules
5. Configuration Modules 5. The Key Providers
The goal of splitting WireNix into modules is both for my own sanity when The goal of splitting WireNix into modules is both for my own sanity when
developing, and to make it hackable without requiring users to make their own developing, and to make it hackable without requiring users to make their own
@ -204,12 +206,10 @@ essentially rewriting this flake however you see fit, all without making a fork
scratch). scratch).
## ACL ## ACL
The shared ACL configuration should describe the full network topology. It does The shared ACL configuration describes the full network topology. It does not
not need to consist only of NixOS peers (although at the moment, other peers need to consist only of NixOS peers The details of this file are documented in
will have to be configured manually to conform to the expected settings). The the [[Top Level ACL]] section. You can make your own ACL configuration format so
details of this file are documented in the `Top Level ACL` section. long as you keep the "`version`" field and set it to some unique name.
You can make your own ACL configuration format so long as you keep the
`version` field and set it to some unique name.
## Parser Modules ## Parser Modules
Parser Modules are responsible for taking an ACL and converting it to the Parser Modules are responsible for taking an ACL and converting it to the
@ -241,16 +241,15 @@ version = "myParser";
## Intermediate Configuration ## Intermediate Configuration
The Intermediate Configuration is a recursive attrset that is more suited for The Intermediate Configuration is a recursive attrset that is more suited for
being used in a NixOS configuration than the ACL Configuration. being used in a NixOS configuration than the ACL Configuration. Unlike the ACL,
Unlike the ACL, the intermediate configuration is more verbose, easier to the intermediate configuration is more verbose, easier to traverse, contains
traverse, repeats itself often, and is recursive. This allows cross version duplicate information, and is recursive. This allows cross version
compatibility so long as the intermediate configuration doesn't change. Any compatibility so long as the intermediate configuration doesn't change. Any
changes will likely only be the addition of optional features that do not changes will likely only be the addition of optional features that do not
interfere with existing intermediate configuration use, though at this stage interfere with existing intermediate configuration use, though at this stage
there are no guarentees. there are no guarentees.
It can be assumed that all types mentioned are types for the intermediate Take note while reading that certain structures may be similar to the ACL,
connection and NOT the related to types in the ACL. The intermediate but they are not necessarily the same as their ACL counterparts.
configuration has the following structure:
### Root Structure ### Root Structure
```typescript ```typescript
@ -258,6 +257,7 @@ type intermediateConfiguration = {
peers: {[peerName: str]: peer}; peers: {[peerName: str]: peer};
subnets: {[subnetName: str]: subnet}; subnets: {[subnetName: str]: subnet};
groups: {[groupName: str]: group}; groups: {[groupName: str]: group};
extraArgs?: attrset;
} }
``` ```
@ -266,10 +266,10 @@ type intermediateConfiguration = {
```typescript ```typescript
type peer = { type peer = {
subnetConnections: {[subnetName: str]: subnetConnection}; subnetConnections: {[subnetName: str]: subnetConnection};
groups: {[groupName: str]: group}
publicKey: str; publicKey: str;
privateKeyFile: str; privateKeyFile: str;
extraArgs?: any; groups?: {[groupName: str]: group}
extraArgs?: attrset;
}; };
``` ```
@ -279,7 +279,8 @@ type peer = {
```typescript ```typescript
type subnet = { type subnet = {
peers: {[peerName: str]: peer}; peers: {[peerName: str]: peer};
extraArgs?: any; presharedKeyFile?: str;
extraArgs?: attrset;
}; };
``` ```
@ -288,30 +289,30 @@ type subnet = {
```typescript ```typescript
type group = { type group = {
peers: {[peerName: str]: peer}; peers: {[peerName: str]: peer};
extraArgs?: any; extraArgs?: attrset;
}; };
``` ```
### Peer Connection ### Subnet Connection
```typescript ```typescript
type peerConnection = { type subnetConnection = {
peer: peer; subnet: subnet;
ipAddresses: str[]; ipAddresses: str[];
endpoint: endpoint; listenPort: int;
extraArgs?: any; peerConnections: {[peerName: str]: peerConnection};
extraArgs?: attrset;
}; };
``` ```
### Subnet Connection ### Peer Connection
```typescript ```typescript
type subnetConnection = { type peerConnection = {
subnet: subnet; peer: peer;
ipAddresses: str[]; ipAddresses: str[];
listenPort: int; endpoint: endpoint;
peerConnections: {[peerName: str]: peerConnection}; extraArgs?: attrset;
extraArgs?: any;
}; };
``` ```
@ -324,14 +325,10 @@ type endpoint = {
persistentKeepalive?: int; persistentKeepalive?: int;
dynamicEndpointRefreshSeconds?: int; dynamicEndpointRefreshSeconds?: int;
dynamicEndpointRefreshRestartSeconds?: int; dynamicEndpointRefreshRestartSeconds?: int;
extraArgs?: any; extraArgs?: attrset;
}; };
``` ```
Unlike the ACL, this structure is recursive, resembling an arbitrary graph.
This graph can be traversed back and forth in circles until you run out of
stack space.
## Configuration Modules ## Configuration Modules
Configuration Modules take the Key provider list and Intermediate Configuration Configuration Modules take the Key provider list and Intermediate Configuration
to produce NixOS configurations. By default, there exist configuration modules to produce NixOS configurations. By default, there exist configuration modules
@ -381,7 +378,7 @@ wirenix.keyProviders = ["myKeyProvider"];
# Integrations: # Integrations:
By default, WireNix supports setting wireguard keypairs with By default, WireNix supports setting wireguard keypairs with
[agenix-rekey](https://github.com/oddlama/agenix-rekey). [agenix-rekey](https://github.com/oddlama/agenix-rekey).
WireNix also supports networkd, network manager, and the nixos static network WireNix also supports using either networkd or the nixos static network
configuration (default). configuration (default).
Using networkd: Using networkd:

Write Preview
Loading…
Cancel
Save