Add documentation for admin create-network

This commit is contained in:
Brian Picciano 2022-11-03 15:38:31 +01:00
parent b935457439
commit 5c8c24e73e
3 changed files with 152 additions and 2 deletions

View File

@ -83,6 +83,7 @@ likely operators as well.
Documentation for admins: Documentation for admins:
* [Creating a New Network](docs/admin/creating-a-new-network.md)
* [Adding a Host to the Network](docs/admin/adding-a-host-to-the-network.md) * [Adding a Host to the Network](docs/admin/adding-a-host-to-the-network.md)
* Removing a Host From the Network (TODO) * Removing a Host From the Network (TODO)

View File

@ -0,0 +1,149 @@
# Creating a New Network
This guide is for those who wish to start a new cryptic-net network of their
own.
By starting a new cryptic-net network, you are becoming the administrator of a
network. Be aware that being a network administrator is not necessarily easy,
and the users of your network will frequently need your help in order to have a
good experience. It can be helpful to have others with which you are
administering the network, in order to share responsibilities.
## Requirements
Creating a network is done using a single host, which will become the first host
in the network.
The configuration used during network creation will be identical to that used
during normal operation of the host, so be prepared to commit to that
configuration for a non-trivial amount of time.
The requirements for this host are:
* A public static IP, or a dynamic public IP with [dDNS][ddns] set up.
* There should be UDP port which is accessible publicly over that IP/DNS name.
This may involve forwarding the UDP port in your gateway if the host is
behind a NAT, and/or allowing traffic on that UDP port in your hosts
firewall.
* At least 300 GB of disk storage space.
* At least 3 directories should be chosen, each of which will be committing at
least 100GB. Ideally these directories should be on different physical
disks, but if that's not possible it's ok. See the Next Steps section.
* None of the resources being used for this network (the UDP port or storage
locations) should be being used by other networks.
## Step 1: Create a `daemon.yml` File
A `daemon.yml` will need to be created for use during network creation. You can
create a new `daemon.yml` with default values filled in by doing:
```
cryptic-net admin create-network --dump-config > /path/to/daemon.yml
```
Open this file in a text editor and perform the following changes:
* Set the `vpn.public_addr` field to the `host:port` your host is accessible on,
where `host` is the static public IP/DNS name of your host, and `port` is the
UDP port which is publicly accessible.
* Configure 3 (at least) allocations in the `storage.allocations` section.
Save and close the file.
## Step 2: Choose Parameters
There are some key parameters which must be chosen when creating a new network.
These will remain constant throughout the lifetime of the network, and so should
be chosen with care.
* Subnet: The IP subnet (or CIDR) will look something like `10.10.0.0/16`, where
the `/16` indicates that all IPs from `10.10.0.0` to `10.10.255.255` are
included. It's recommended to choose from the [ranges reserved for private
networks](https://en.wikipedia.org/wiki/IPv4#Private_networks), but within
that selection the choice is up to you.
* Domain: cryptic-net is shipped with a DNS server which will automatically
configure itself with all hosts in the network, with each DNS entry taking the
form of `hostname.hosts.domain`, where `domain` is the domain chosen in this
step. The domain may be a valid public domain or not, it's up to you.
* Hostname: The hostname of your host, which will be the first host in the
network, must be chosen at this point. You can reference the [Adding a Host to
the Network](./adding-a-host-to-the-network.md) document for the constraints
on the hostname.
* IP: The IP of your host, which will be the first host in the network. This IP
must be within the chosen subnet range.
## Step 3: Prepare to Encrypt `admin.yml`
The `admin.yml` file (which will be created in the next step) is the most
sensitive part of a cryptic-net network. If it falls into the wrong hands it can
be used to completely compromise your network, impersonate hosts on the network,
and will likely lead to someone stealing or deleting all of your data.
Therefore it is important that the file remains encrypted when it is not being
used, and that it is never stored to disk in its decrypted form.
This guide assumes that you have GPG already set up with your own secret key,
and that you are familiar with how it works. There is no requirement to use GPG,
if you care to use a different method.
## Step 4: Create the `admin.yml` File
To create the `admin.yml` file, which effectively creates the network itself,
you can run:
```
sudo cryptic-net admin create-network \
--config /path/to/daemon.yml \
--domain <domain> \
--ip <ip/subnet-prefix> \
--name <hostname> \
| gpg -e -r <my gpg email> \
> admin.yml.gpg
```
A couple of notes here:
* The `--ip` parameter is formed from both the subnet and the IP you chose
within it. So if your subnet is `10.10.0.0/16`, and your chosen IP in that
subnet is `10.10.4.20`, then your `--ip` parameter will be `10.10.4.20/16`.
* Only one gpg recipient is specified. If you intend on including other users as
network administrators you can add them to the recipients list at this step,
so they will be able to use the `admin.yml` file as well. You can also
manually add them as recipients later.
You will see a lot of output, as `create-network` starts up many child processes
in order to set the network up. It should exit successfully on its own after a
few seconds.
At this point you should have an `admin.yml.gpg` file in your current directory.
## Step 5: Run the Daemon
The cryptic-net daemon can be run now, using the following command:
```
sudo cryptic-net daemon -c /path/to/daemon.yml
```
**NOTE** that you _must_ use the same `daemon.yml` file used when creating the
network for the daemon itself.
At this point your host, and your network, are ready to go! You can reference
the [Getting Started](../user/getting-started.md) document to set up your
host's daemon process in a more permanent way.
## Next Steps
* Add users
* Fix directories
[ddns]: https://www.cloudflare.com/learning/dns/glossary/dynamic-dns/

View File

@ -4,14 +4,14 @@ If your host machine can be reasonably sure of being online most, if not all, of
the time, and has 100GB or more of unused drive space you'd like to contribute the time, and has 100GB or more of unused drive space you'd like to contribute
to the network, then this document is for you. to the network, then this document is for you.
## Create daemon.yml ## Create `daemon.yml`
First, if you haven't already, [create a `daemon.yml` First, if you haven't already, [create a `daemon.yml`
file](../user/creating-a-daemonyml-file.md). This will be used to file](../user/creating-a-daemonyml-file.md). This will be used to
configure your `cryptic-net daemon` process with the storage locations and configure your `cryptic-net daemon` process with the storage locations and
capacities you want to contribute. capacities you want to contribute.
## Edit daemon.yml ## Edit `daemon.yml`
Open your `daemon.yml` file in a text editor, and find the Open your `daemon.yml` file in a text editor, and find the
`storage.allocations` section. `storage.allocations` section.