outline_vpn_api

Ruby API wrapper for Outline VPN Server https://getoutline.org/ It provides a simple interface to manage and retrieve information about VPN keys, metrics, and other related functionalities.

Installation

Requires Ruby 3.4 or newer.

gem install outline_vpn_api

Usage

Initialization

To start using the client, initialize it with the API URL:

client = OutlineVpnApi.new('YOUR_API_URL')

Outline servers present a self-signed certificate, so by default the client does not verify it. Pass the certSha256 fingerprint that Outline Manager shows next to the API URL to pin the certificate instead:

client = OutlineVpnApi.new('YOUR_API_URL', cert_sha256: 'AB:CD:...')

With a fingerprint set, a connection to any other certificate is rejected with OutlineVpnApi::CertificateError. Without one the connection can be intercepted, and since the API key is part of the URL an interceptor gains full control of the server — pinning is strongly recommended.

Requests time out after 30 seconds by default:

client = OutlineVpnApi.new('YOUR_API_URL', timeout: 10)

Methods

keys_list

Fetches a list of all keys:

keys = client.keys_list

transferred_data_by_id

Fetches the transferred data metrics:

data = client.transferred_data_by_id

create_key

Creates a new key:

new_key = client.create_key

set_limit(key_id, limit)

Sets a data limit for a specific key. Returns true:

client.set_limit('KEY_ID', LIMIT_IN_BYTES)

rename_key(key_id, name)

Renames a specific key. Returns true:

client.rename_key('KEY_ID', 'NEW_NAME')

delete_key(key_id)

Deletes a specific key. Returns true:

client.delete_key('KEY_ID')

Errors

All errors inherit from OutlineVpnApi::Error:

  • OutlineVpnApi::ResponseError — the server replied with a non-2xx status, or with a body that is not valid JSON. Exposes #code and #body.
  • OutlineVpnApi::ConnectionError — the server could not be reached, or the request timed out.
  • OutlineVpnApi::CertificateError — a pinned fingerprint was given and the server's certificate did not match it. Subclass of ConnectionError.
begin
  client.keys_list
rescue OutlineVpnApi::ResponseError => e
  warn "Outline returned #{e.code}: #{e.body}"
end

Dependencies

  • httparty (>= 0.24.0): Used for making HTTP requests.
  • json: Used for parsing JSON responses.

Contributing

If you'd like to contribute to this project, please submit a pull request with your changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.