diff --git a/README.md b/README.md index 6809b69..216ab94 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,11 @@ # Olm -Olm is a [WireGuard](https://www.wireguard.com/) tunnel manager designed to securely connect to private resources. By using Olm, you don't need to manage complex WireGuard tunnels. +Olm is a [WireGuard](https://www.wireguard.com/) tunnel client designed to securely connect you computer to Newt sites running on remote networks. ### Installation and Documentation Olm is used with Pangolin and Newt as part of the larger system. See documentation below: -- [Installation Instructions](https://docs.fossorial.io) - [Full Documentation](https://docs.fossorial.io) ## Key Functions @@ -17,82 +16,65 @@ Using the Olm ID and a secret, the olm will make HTTP requests to Pangolin to re ### Receives WireGuard Control Messages -When Olm receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using [netstack](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go) fully in user space. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up. - -### Receives Proxy Control Messages - -When Olm receives WireGuard control messages, it will use the information encoded to create a local low level TCP and UDP proxies attached to the virtual tunnel in order to relay traffic to programmed targets. +When Olm receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel on your computer to a remote Newt. It will ping over the tunnel to ensure the peer is brought up. ## CLI Args -- `endpoint`: The endpoint where both Gerbil and Pangolin reside in order to connect to the websocket. -- `id`: Olm ID generated by Pangolin to identify the olm. -- `secret`: A unique secret (not shared and kept private) used to authenticate the olm ID with the websocket in order to receive commands. -- `dns`: DNS server to use to resolve the endpoint -- `log-level` (optional): The log level to use. Default: INFO +- `endpoint`: The endpoint where both Gerbil and Pangolin reside in order to connect to the websocket. +- `id`: Olm ID generated by Pangolin to identify the olm. +- `secret`: A unique secret (not shared and kept private) used to authenticate the olm ID with the websocket in order to receive commands. +- `mtu` (optional): MTU for the internal WG interface. Default: 1280 +- `dns` (optional): DNS server to use to resolve the endpoint. Default: 8.8.8.8 +- `log-level` (optional): The log level to use (DEBUG, INFO, WARN, ERROR, FATAL). Default: INFO +- `ping-interval` (optional): Interval for pinging the server. Default: 3s +- `ping-timeout` (optional): Timeout for each ping. Default: 5s +- `interface` (optional): Name of the WireGuard interface. Default: olm +- `enable-http` (optional): Enable HTTP server for receiving connection requests. Default: false +- `http-addr` (optional): HTTP server address (e.g., ':9452'). Default: :9452 +- `holepunch` (optional): Enable hole punching. Default: false + +## Environment Variables + +All CLI arguments can also be set via environment variables: + +- `PANGOLIN_ENDPOINT`: Equivalent to `--endpoint` +- `OLM_ID`: Equivalent to `--id` +- `OLM_SECRET`: Equivalent to `--secret` +- `MTU`: Equivalent to `--mtu` +- `DNS`: Equivalent to `--dns` +- `LOG_LEVEL`: Equivalent to `--log-level` +- `INTERFACE`: Equivalent to `--interface` +- `HTTP_ADDR`: Equivalent to `--http-addr` +- `PING_INTERVAL`: Equivalent to `--ping-interval` +- `PING_TIMEOUT`: Equivalent to `--ping-timeout` +- `HOLEPUNCH`: Set to "true" to enable hole punching (equivalent to `--holepunch`) Example: ```bash -./olm \ +olm \ --id 31frd0uzbjvp721 \ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ --endpoint https://example.com ``` -You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using environment vars (recommended): +## Hole Punching -```yaml -services: - olm: - image: fosrl/olm - container_name: olm - restart: unless-stopped - environment: - - PANGOLIN_ENDPOINT=https://example.com - - OLM_ID=2ix2t8xk22ubpfy - - OLM_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 -``` +In the default mode, olm "relays" traffic through Gerbil in the cloud to get down to newt. This is a little more reliable. Support for NAT hole punching is also EXPERIMENTAL right now using the `--holepunch` flag. This will attempt to orchestrate a NAT hole punch between the two sites so that traffic flows directly. This will save data costs and speed. If it fails it should fall back to relaying. -You can also pass the CLI args to the container: +Right now, basic NAT hole punching is supported. We plan to add: -```yaml -services: - olm: - image: fosrl/olm - container_name: olm - restart: unless-stopped - command: - - --id 31frd0uzbjvp721 - - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 - - --endpoint https://example.com -``` - -Finally a basic systemd service: - -``` -[Unit] -Description=Olm VPN Olm -After=network.target - -[Service] -ExecStart=/usr/local/bin/olm --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com -Restart=always -User=root - -[Install] -WantedBy=multi-user.target -``` - -Make sure to `mv ./olm /usr/local/bin/olm`! +- [ ] Birthday paradox +- [ ] UPnP +- [ ] LAN detection ## Windows Service -On Windows, Olm can be installed and run as a Windows service. This allows it to start automatically at boot and run in the background. +On Windows, olm has to be installed and run as a Windows service. When running it with the cli args live above it will attempt to install and run the service to function like a cli tool. You can also run the following: ### Service Management Commands -```cmd +``` # Install the service olm.exe install @@ -108,50 +90,40 @@ olm.exe status # Remove the service olm.exe remove -# Run in debug mode (console output) +# Run in debug mode (console output) with our without id & secret olm.exe debug # Show help olm.exe help ``` -**Helper Scripts**: For easier service management, you can use the provided helper scripts: -- `olm-service.bat` - Batch script (requires Administrator privileges) -- `olm-service.ps1` - PowerShell script with better error handling - -Example using the batch script: -```cmd -# Run as Administrator -olm-service.bat install -olm-service.bat start -olm-service.bat status -``` - ### Service Configuration When running as a service, Olm will read configuration from environment variables or you can modify the service to include command-line arguments: 1. Install the service: `olm.exe install` 2. Configure the service with your credentials using Windows Service Manager or by setting system environment variables: - - `PANGOLIN_ENDPOINT=https://example.com` - - `OLM_ID=your_olm_id` - - `OLM_SECRET=your_secret` + - `PANGOLIN_ENDPOINT=https://example.com` + - `OLM_ID=your_olm_id` + - `OLM_SECRET=your_secret` 3. Start the service: `olm.exe start` ### Service Logs When running as a service, logs are written to: -- Windows Event Log (Application log, source: "OlmWireguardService") -- Log files in: `%PROGRAMDATA%\Olm\logs\olm.log` + +- Windows Event Log (Application log, source: "OlmWireguardService") +- Log files in: `%PROGRAMDATA%\olm\logs\olm.log` You can view the Windows Event Log using Event Viewer or PowerShell: + ```powershell Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10 ``` ## Build -### Container +### Container Ensure Docker is installed.