diff --git a/installation-linux-deb.md b/installation-linux-deb.md new file mode 100644 index 0000000..67b0928 --- /dev/null +++ b/installation-linux-deb.md @@ -0,0 +1,72 @@ +--- +tags: dontlink +sitemap: true +--- + +# Installing on Debian, Ubuntu, elementaryOS + +Yggdrasil is supported on Debian Linux. Debian binary packages exist to simplify +the installation of Yggdrasil. These will also work on any Debian-based +distribution, e.g. elementaryOS. + +### Package install from an Aptitude repository + +To start with, import the repository key to your `gpg` keyring and export it +to your `apt` keyring: + +``` +gpg --fetch-keys https://neilalexander.s3.eu-west-2.amazonaws.com/deb/key.txt +gpg --export 569130E8CA20FBC4CB3FDE555898470A764B32C9 | sudo apt-key add - +``` + +Add the repository into your `apt` sources: +``` +echo 'deb http://neilalexander.s3.eu-west-2.amazonaws.com/deb/ debian yggdrasil' | sudo tee /etc/apt/sources.list.d/yggdrasil.list +sudo apt-get update +``` + +**Note**: The repository also works over HTTPS - you will need to `sudo apt-get install apt-transport-https` and then edit the above URL so that it starts with `https://` instead of `http://` in `/etc/apt/sources.list.d/yggdrasil.list`. + +Install Yggdrasil: +``` +sudo apt-get install yggdrasil +``` +Configuration will be generated automatically into `/etc/yggdrasil.conf` when +the package is installed, and the Yggdrasil service will automatically be +installed into `systemd`. + +Enable and start the service after install/upgrade: +``` +sudo systemctl enable yggdrasil +sudo systemctl start yggdrasil +``` + +### One-off package install from CircleCI + +Visit our [Builds](builds.md) page and download the relevant `.deb` file, then +install it on your system. If you want to install the latest `.deb` from the +`master` branch: +``` +curl -so- "https://circleci.com/api/v1.1/project/github/yggdrasil-network/yggdrasil-go/latest/artifacts?branch=master&filter=successful" | \ +egrep -o "https.*yggdrasil\-.*$(dpkg --print-architecture).deb" | \ +while read line; do curl -O $line && dpkg -i $(basename $line); done +``` +Configuration will be generated automatically into `/etc/yggdrasil.conf` when +the package is installed, and the Yggdrasil service will automatically be +installed into systemd and started. + +### Making configuration changes + +Modify the `/etc/yggdrasil.conf` file and then either reload the config: +``` +systemctl reload yggdrasil +``` +... or restart the Yggdrasil daemon altogether: +``` +systemctl restart yggdrasil +``` + +### After installation + +Read the [Linux platform page](platform-linux.md) page for further +information about Linux platform support. diff --git a/installation-linux-edgeos.md b/installation-linux-edgeos.md new file mode 100644 index 0000000..5bbfa73 --- /dev/null +++ b/installation-linux-edgeos.md @@ -0,0 +1,57 @@ +--- +tags: dontlink +sitemap: true +--- + +# Installing on Ubiquiti EdgeOS + +Yggdrasil is supported on the Ubiquiti EdgeRouter using the +[vyatta-yggdrasil](https://github.com/neilalexander/vyatta-yggdrasil) package. + +Perform installation steps over SSH by connecting to the EdgeRouter as the +`ubnt` user, e.g. `ssh ubnt@192.168.1.1`, or another admin-level user if +configured. + +### Package install from an Aptitude repository + +Start by adding the GPG key: +``` +curl -o- https://neilalexander.s3.eu-west-2.amazonaws.com/deb/key.txt | sudo apt-key add - +``` + +Then add the repository: +``` +configure +set system package repository yggdrasil distribution edgerouter +set system package repository yggdrasil components yggdrasil +set system package repository yggdrasil url http://neilalexander.s3.eu-west-2.amazonaws.com/deb/ +commit +save +``` + +Then install the `vyatta-yggdrasil` package: +``` +sudo apt-get update +sudo apt-get install vyatta-yggdrasil +``` + +Yggdrasil can then be updated in the future by updating the packages: +``` +sudo apt-get update +sudo apt-get upgrade +``` + +### One-off package install from CircleCI + +If you do not want to configure the repository above, you can perform a one-off +installation by [downloading the latest vyatta-yggdrasil `.deb` +package](https://circleci.com/api/v1.1/project/github/yggdrasil-network/yggdrasil-go/latest/artifacts) and then install it: +``` +curl -O https://xx-xxxxxxxxx-gh.circle-artifacts.com/x/vyatta-yggdrasil-x.x.xxx-mipsel.deb +sudo dpkg -i vyatta-yggdrasil-x.x.xxx-mipsel.deb +``` + +### After installation + +Read the [EdgeRouter platform page](platform-edgerouter.md) page for information +on how to configure Yggdrasil and guidance on modifying the configuration. diff --git a/installation-linux-other.md b/installation-linux-other.md new file mode 100644 index 0000000..9931a5b --- /dev/null +++ b/installation-linux-other.md @@ -0,0 +1,87 @@ +--- +tags: dontlink +sitemap: true +--- + +# Installing manually on Linux + +Yggdrasil is supported on Linux. You can either [download the latest binary from +CircleCI](builds.md) or you can build from source. + +### Build from source + +Linux has most of the tools needed to build Yggdrasil from source - you just +need to install the Go toolchain. Yggdrasil requires Go 1.11 as a minimum. + +- Install [the latest version of Go](https://golang.org/dl/) for your platform + - Using [godeb](https://github.com/niemeyer/godeb) to install Go is + recommended for Debian-based distributions + +Clone the repository and build: +``` +cd /path/to +git clone https://github.com/yggdrasil-network/yggdrasil-go +``` + +Build Yggdrasil: +``` +cd /path/to/yggdrasil-go +./build +``` + +The build will produce `yggdrasil` and `yggdrasilctl` binaries - copy these +into a suitable location: +``` +sudo cp {yggdrasil,yggdrasilctl} /usr/local/bin +``` + +##### Debug builds +You can create a debug build by running `./build -d` instead of +`./build`. Debug builds contain profiling code as well as additional debugging +symbols. They are likely to be larger files as a result. + +### Install systemd service + +systemd service scripts are included in the `contrib/systemd/` folder so that it +runs automatically in the background (using `/etc/yggdrasil.conf` for +configuration). + +Create the `yggdrasil` group on your system - the `systemd` service will run +with this group: +``` +sudo groupadd --system yggdrasil +``` + +Copy the service files: +``` +sudo cp contrib/systemd/yggdrasil.service /etc/systemd/system +sudo systemctl daemon-reload +``` + +Enable and start Yggdrasil: +``` +sudo systemctl enable yggdrasil +sudo systemctl start yggdrasil +``` + +Once installed as a systemd service, you can read the `yggdrasil` output using +`systemctl` or `journalctl`: +``` +systemctl status yggdrasil +journalctl -u yggdrasil +``` + +### Generate configuration + +Generate an initial Yggdrasil configuration file: +``` +sudo yggdrasil -genconf > /etc/yggdrasil.conf +``` + +You can make changes to this file as described in the +[Configuration](configuration.md) page. + +### After installation + +Read the [Linux platform page](platform-linux.md) page for further +information about Linux platform support. diff --git a/installation-linux-rpm.md b/installation-linux-rpm.md new file mode 100644 index 0000000..d8f5d06 --- /dev/null +++ b/installation-linux-rpm.md @@ -0,0 +1,76 @@ +--- +tags: dontlink +sitemap: true +--- + +# Installing on Red Hat Enterprise Linux, Fedora, CentOS + +RPM binary packages exist to simplify the installation of Yggdrasil. These +will also work on any other RPM-based distribution. + +### Package install from an RPM repository + +To start with, import the repository key to your `gpg` keyring and export it +to your `rpm` keyring: +``` +gpg --fetch-keys https://neilalexander.s3.eu-west-2.amazonaws.com/deb/key.txt +gpg --armor --no-comment --export-options export-minimal --export 569130E8CA20FBC4CB3FDE555898470A764B32C9 | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-yggdrasil +``` + +Add the repository: +``` +sudo cat > /etc/yum.repos.d/yggdrasil.repo << EOF +[yggdrasil] +name = Yggdrasil +baseurl = https://neilalexander.s3.eu-west-2.amazonaws.com/rpm/ +gpgcheck=1 +gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-yggdrasil +EOF +``` + +Create the `yggdrasil` group on your system: +``` +sudo groupadd --system yggdrasil +``` + +Install Yggdrasil: +``` +sudo dnf install yggdrasil +``` +Configuration will be generated automatically into `/etc/yggdrasil.conf` when +the package is installed, and the Yggdrasil service will automatically be +installed into `systemd`. + +Enable and start the service after install/upgrade: +``` +sudo systemctl enable yggdrasil +sudo systemctl start yggdrasil +``` + +### One-off package install from CircleCI + +Visit our [Builds](builds.md) page and download the relevant `.rpm` file, then +install it on your system: +``` +sudo groupadd --system yggdrasil +sudo rpm -i yggdrasil...rpm +``` +Configuration will be generated automatically into `/etc/yggdrasil.conf` when +the package is installed, and the Yggdrasil service will automatically be +installed into systemd and started. + +### Making configuration changes + +Modify the `/etc/yggdrasil.conf` file and then either reload the config: +``` +systemctl reload yggdrasil +``` +... or restart the Yggdrasil daemon altogether: +``` +systemctl restart yggdrasil +``` + +### After installation + +Read the [Linux platform page](platform-linux.md) page for further +information about Linux platform support. diff --git a/installation.md b/installation.md new file mode 100644 index 0000000..5503900 --- /dev/null +++ b/installation.md @@ -0,0 +1,12 @@ +--- +sitemap: true +--- + +# Installation + +## Linux + +- [Debian, Ubuntu, elementaryOS](installation-linux-deb.md) +- [Red Hat Enterprise Linux, Fedora, CentOS](installation-linux-rpm.md) +- [Ubiquiti EdgeOS](installation-linux-edgeos.md) +- [Other distributions or build from source](installation-linux-other.md) diff --git a/platform-edgerouter.md b/platform-edgerouter.md index bf94a39..3bbbbf6 100644 --- a/platform-edgerouter.md +++ b/platform-edgerouter.md @@ -12,44 +12,6 @@ Yggdrasil is supported on the Ubiquiti EdgeRouter using the [vyatta-yggdrasil](h - Although your Yggdrasil configuration will persist, the Yggdrasil package itself **does not** survive an upgrade of the EdgeRouter firmware. You must re-add the repository GPG key and re-install the `vyatta-yggdrasil` package after a system upgrade. - After upgrading firmware and reinstalling Yggdrasil, use `load` to reload your configuration and then `commit` to make it effective again. Do not run `save` until after you have reloaded your configuration. -## Installation - -Perform installation steps over SSH by connecting to the EdgeRouter as the `ubnt` user, e.g. `ssh ubnt@192.168.1.1`, or another admin-level user if configured. - -### From an Internet repository - -Start by adding the GPG key: -``` -curl -o- https://neilalexander.s3.eu-west-2.amazonaws.com/deb/key.txt | sudo apt-key add - -``` -Then add the repository: -``` -configure -set system package repository yggdrasil distribution edgerouter -set system package repository yggdrasil components yggdrasil -set system package repository yggdrasil url http://neilalexander.s3.eu-west-2.amazonaws.com/deb/ -commit -save -``` -Then install the `vyatta-yggdrasil` package: -``` -sudo apt-get update -sudo apt-get install vyatta-yggdrasil -``` -Yggdrasil can then be updated in the future by updating the packages: -``` -sudo apt-get update -sudo apt-get upgrade -``` - -### One-off installation - -If you do not want to configure the repository above, you can perform a one-off installation by [downloading the latest vyatta-yggdrasil .deb package](https://circleci.com/api/v1.1/project/github/yggdrasil-network/yggdrasil-go/latest/artifacts) and then install it: -``` -curl -O https://xx-xxxxxxxxx-gh.circle-artifacts.com/x/vyatta-yggdrasil-x.x.xxx-mipsel.deb -sudo dpkg -i vyatta-yggdrasil-x.x.xxx-mipsel.deb -``` - ## Generate configuration Configuration for Yggdrasil is generated automatically when you create an interface, e.g. as `tun0`: diff --git a/platform-linux.md b/platform-linux.md index aa65345..bec7cb1 100644 --- a/platform-linux.md +++ b/platform-linux.md @@ -9,175 +9,7 @@ Yggdrasil is well supported on Linux. ## Notes -- Should work with any kernel that includes `tun` and/or `tap`. +- Should work with any kernel that includes the `tun` and/or `tap` modules. - The maximum MTU size supported on Linux is 65535 in TUN mode and 65521 in TAP mode. -- Binary `.deb` packages are available for Debian, Ubuntu, elementaryOS and similar distributions. -- Binary `.rpm` packages are available for Red Hat Enterprise Linux, Fedora, CentOS and similar distributions. - IPv6 needs to be enabled in order for Yggdrasil to work - IPv6 is usually enabled by default, but if not, enable using `sysctl -w net.ipv6.conf.all.disable_ipv6=0` or similar. - If using TUN/TAP then `/dev/net/tun` should be present on your system. - -## Debian, Ubuntu, elementaryOS (with systemd) - -Debian binary packages exist to simplify the installation of Yggdrasil. These -will also work on any Debian-based distribution. - -### From CircleCI - -Visit our [Builds](builds.md) page and download the relevant `.deb` file, then -install it on your system. If you want to install the latest `.deb` from the -`master` branch: -``` -curl -so- "https://circleci.com/api/v1.1/project/github/yggdrasil-network/yggdrasil-go/latest/artifacts?branch=master&filter=successful" | \ -egrep -o "https.*yggdrasil\-.*$(dpkg --print-architecture).deb" | \ -while read line; do curl -O $line && dpkg -i $(basename $line); done -``` -Configuration will be generated automatically into `/etc/yggdrasil.conf` when -the package is installed, and the Yggdrasil service will automatically be -installed into systemd and started. - -### From an Internet repository - -To start with, import the repository key to your gpg keyring and export it -to your apt keyring: - -``` -gpg --fetch-keys https://neilalexander.s3.eu-west-2.amazonaws.com/deb/key.txt -gpg --export 569130E8CA20FBC4CB3FDE555898470A764B32C9 | sudo apt-key add - -``` - -Add the repository: -``` -echo 'deb http://neilalexander.s3.eu-west-2.amazonaws.com/deb/ debian yggdrasil' | sudo tee /etc/apt/sources.list.d/yggdrasil.list -sudo apt-get update -``` - -**Note**: The repository also works over HTTPS - you will need to `sudo apt-get install apt-transport-https` and then edit the above URL so that it starts with `https://` instead of `http://` in `/etc/apt/sources.list.d/yggdrasil.list`. - -Install Yggdrasil: -``` -sudo apt-get install yggdrasil -``` -Configuration will be generated automatically into `/etc/yggdrasil.conf` when -the package is installed, and the Yggdrasil service will automatically be -installed into systemd and started. - -## Red Hat Enterprise Linux, Fedora, CentOS (with systemd) - -RPM binary packages exist to simplify the installation of Yggdrasil. These -will also work on any other RPM-based distribution. - -### From CircleCI - -Visit our [Builds](builds.md) page and download the relevant `.rpm` file, then -install it on your system: -``` -sudo groupadd --system yggdrasil -sudo rpm -i yggdrasil...rpm -``` -Configuration will be generated automatically into `/etc/yggdrasil.conf` when -the package is installed, and the Yggdrasil service will automatically be -installed into systemd and started. - -### From an Internet repository - -To start with, download the repository key: -``` -gpg --fetch-keys https://neilalexander.s3.eu-west-2.amazonaws.com/deb/key.txt -gpg --armor --no-comment --export-options export-minimal --export 569130E8CA20FBC4CB3FDE555898470A764B32C9 | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-yggdrasil -``` - -Add the repository: -``` -sudo cat > /etc/yum.repos.d/yggdrasil.repo << EOF -[yggdrasil] -name = Yggdrasil -baseurl = https://neilalexander.s3.eu-west-2.amazonaws.com/rpm/ -gpgcheck=1 -gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-yggdrasil -EOF -``` - -Create the `yggdrasil` group: -``` -sudo groupadd --system yggdrasil -``` - -Install Yggdrasil: -``` -sudo dnf install yggdrasil -``` -Enable and start the service after install/upgrade: -``` -sudo systemctl enable yggdrasil -sudo systemctl start yggdrasil -``` - -## Other Distributions - -[Download the latest Yggdrasil binary](https://circleci.com/api/v1.1/project/github/yggdrasil-network/yggdrasil-go/latest/artifacts) and install it: -``` -sudo cp ~/yggdrasil-x.x.xx-linux-amd64 /usr/local/bin/yggdrasil -sudo chmod +x /usr/local/bin/yggdrasil -``` -Alternatively, compile Yggdrasil from source (below) and install: -``` -sudo cp /path/to/yggdrasil-go/yggdrasil /usr/local/bin/yggdrasil -sudo chmod +x /usr/local/bin/yggdrasil -``` - -## Generate configuration - -If you do not have a configuration file, you should generate configuration -before starting Yggdrasil: -``` -sudo yggdrasil -genconf > /etc/yggdrasil.conf -``` - -## Run Yggdrasil - -### Run once - -Open a shell and start Yggdrasil using your generated configuration: -``` -sudo nohup yggdrasil -useconffile /etc/yggdrasil.conf & -``` -Alternatively, start Yggdrasil in auto-configuration mode: -``` -sudo nohup yggdrasil -autoconf & -``` - -### Run with systemd - -systemd service scripts are included in the `contrib/systemd/` folder so that it -runs automatically in the background (using `/etc/yggdrasil.conf` for -configuration). - -Copy the service files into `/etc/systemd/system`, copy `yggdrasil` into your -`$PATH`, i.e. `/usr/bin`, and then enable the service: -``` -systemctl enable yggdrasil -systemctl start yggdrasil -``` - -Once installed as a systemd service, you can read the `yggdrasil` output: -``` -systemctl status yggdrasil -journalctl -u yggdrasil -``` - -## Build instructions - -Linux has most of the tools needed to build Yggdrasil from source - you just -need to install Go 1.11 or later. - -1. Install Go 1.11 or later, [godeb](https://github.com/niemeyer/godeb) is -recommended for Debian-based distributions). -1. Open a shell, clone the repository and build: -``` -cd /path/to -git clone https://github.com/yggdrasil-network/yggdrasil-go -cd yggdrasil-go -./build -``` -1. The resulting `yggdrasil` file is your build - optionally install it into -your system, as above.