diff --git a/manage/clients/configure-client.mdx b/manage/clients/configure-client.mdx index 1e50797..b3daa8a 100644 --- a/manage/clients/configure-client.mdx +++ b/manage/clients/configure-client.mdx @@ -58,7 +58,9 @@ To ensure Pangolin functions correctly in the background on Android devices, it' Refer to the [documentation in the official repository](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) for the available commands, default values, and more. -## Olm CLI +## Olm (Advanced) + + We recommend using the Pangolin CLI for both user and machine clients if you're looking for a CLI interface. Olm is the underlying client for the Pangolin CLI. @@ -346,3 +348,5 @@ Default locations: Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details. + + diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index fc6f134..c6173f9 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -155,13 +155,100 @@ Replace `{version}` with the desired version and `{architecture}` with your arch 3. **Start Pangolin** - Connect Pangolin by running: + When logged in as a Pangolin user, connect by running: ```bash pangolin up ``` -## Olm CLI + To launch a machine client without logging in, use your client credentials: + + ```bash + pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach + ``` + + + The `--attach` flag runs the client in the foreground instead of spawning it as a background process. + + +Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups. + +### Systemd Service (Pangolin CLI) + +Create a basic systemd service for Pangolin CLI: + +```ini title="/etc/systemd/system/pangolin-cli.service" +[Unit] +Description=Pangolin CLI +After=network.target + +[Service] +ExecStart=/usr/local/bin/pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach +Restart=always +User=root + +[Install] +WantedBy=multi-user.target +``` + + +Make sure to move the binary to `/usr/local/bin/pangolin` before creating the service. Replace `{client_id}`, `{client_secret}`, and `{endpoint_url}` with your machine client credentials and endpoint. + + +### Docker (Pangolin CLI) + +You can run Pangolin CLI with Docker Compose. For example, a service in your `docker-compose.yml` might look like this using environment variables (recommended): + +```yaml +services: + pangolin-cli: + image: pangolin-cli:latest + container_name: pangolin-cli + restart: unless-stopped + network_mode: host + cap_add: + - NET_ADMIN + devices: + - /dev/net/tun:/dev/net/tun + environment: + - PANGOLIN_ENDPOINT=https://app.pangolin.net + - CLIENT_ID=5n52gnzfgl3tdox + - CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9 +``` + +You can also pass the CLI args to the container: + +```yaml +services: + pangolin-cli: + image: pangolin-cli:latest + container_name: pangolin-cli + restart: unless-stopped + network_mode: host + cap_add: + - NET_ADMIN + devices: + - /dev/net/tun:/dev/net/tun + command: + - up + - --id + - "5n52gnzfgl3tdox" + - --secret + - "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9" + - --endpoint + - https://app.pangolin.net + - --attach +``` + +**Docker Configuration Notes:** + +- `network_mode: host` brings the Pangolin CLI network interface to the host system, allowing the WireGuard tunnel to function properly +- `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces +- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces + +## Olm (Advanced) + + Olm CLI is the most basic form of a client. All other clients implement Olm under the hood in some form. @@ -348,3 +435,4 @@ Olm creates a native tun interface. This usually requires sudo / admin permissio 5. If the container is running, shut it down and start it up again. Once /dev/net/tun is available, the olm can run within the LXC. + diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 22a35e9..66aaa1f 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -23,7 +23,7 @@ There are two types of clients: user devices and machines. - Represent a server or automated system instead of a user - Connect with an ID and secret - - Available in CLI form with Pangolin CLI or Olm CLI + - Available in CLI form with Pangolin CLI diff --git a/manage/clients/update-client.mdx b/manage/clients/update-client.mdx index 61fd03e..f1eb3c9 100644 --- a/manage/clients/update-client.mdx +++ b/manage/clients/update-client.mdx @@ -46,28 +46,4 @@ wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pango Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information. - - -## Olm CLI - -Find the latest version in the [GitHub releases](https://github.com/fosrl/olm/releases). - -### Automatic Updates (Recommended) - -If you used the auto installer, simply run it again: - -```bash -curl -fsSL https://static.pangolin.net/get-olm.sh | bash -``` - -### Manual Updates - -Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/olm/releases) and replace your existing binary. - -```bash -wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm -``` - - -Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/olm/releases) for the latest information. - + \ No newline at end of file