Pritunl API Client
API client for Pritunl written in Ruby.
Pritunl is a distributed enterprise vpn server built using the OpenVPN protocol. See the official Pritunl API documentation here: https://pritunl.com/api.html. I am not affiliated with Pritunl at all, but couldn't find a Ruby client for their API. So I scratched my own itch and created it myself.
Installation
gem install pritunl_api_client
Usage
require 'pritunl_api_client'
@pritunl = PritunlApiClient::Client.new(
base_url: 'https://localhost:9700',
api_token: 'p7g444S3IZ5wmFvmzWmx14qACXdzQ25b',
api_secret: 'OpS9fjxkPI3DclkdKDDr6mqYVd0DJh4i',
verify_ssl: false
)
Ping
Server healthcheck.
@pritunl.ping
Status
Returns general information about the pritunl server.
@pritunl.status
{
"host_count" => 1,
"servers_online" => 1,
"hosts_online" => 1,
"server_count" => 2,
"server_version" => "1.11.813.26",
"public_ip" => "10.55.87.4",
"user_count" => 1,
"notification" => "",
"users_online" => 1,
"local_networks" => ["10.55.87.3/31", "10.2.214.0/31"],
"current_host" => "0f273a6c32ed45259c1ecb1ec3ac05ce",
"org_count" => 2
}
Log
Returns a list of server log entries sorted by time.
@pritunl.log
[
{
"timestamp" => 1450429682,
"message" => "Deleted organization 'org1'.",
"id" => "567386a32221390ea53d8047"
},
{
"timestamp" => 1450429682,
"message" => "Deleted user 'user1'.",
"id" => "567386a32221390ea53d8045"
},
{
"timestamp" => 1450429681,
"message" => "Enabled user 'user2'.",
"id" => "567386a22221390ea53d8042"
}
]
Events
Get a list of events (will poll up to 30 seconds)
@pritunl.event( cursor: '55e9f1f1b0e730245677dc31' )
[
{
"id" => "55e9f1f1b0e730245677dc31",
"type" => "users_updated",
"timestamp" => 1388495793,
"resource_id" => "55e9f1f8b0e730245677dc34"
},
{
"id" => "55e9f1f2b0e730245677dc32",
"type" => "server_organizations_updated",
"timestamp" => 1388495805,
"resource_id" => "55e9f1f8b0e730245677dc33"
}
]
Settings
Get system settings.
@pritunl.settings.all
{
"username" => "user6",
"sso_admin" => nil,
"theme" => "dark",
"sso" => nil,
"sso_match" => nil,
"server_cert" => "-----BEGIN CERTIFICATE----------END CERTIFICATE-----",
"public_address" => "10.5.8.46",
"routed_subnet6" => nil,
"email_username" => "user1",
"sso_saml_issuer_url" => nil,
"sso_saml_cert" => nil,
"sso_token" => nil,
"email_password" => true,
"sso_onelogin_key" => nil,
"email_server" => "smtp.example.com",
"auditing" => nil,
"sso_secret" => nil,
"server_key" => "-----BEGIN PRIVATE KEY----------END PRIVATE KEY-----",
"default" => nil,
"sso_host" => nil,
"public_address6" => "2605:1480:2:a210::1",
"secret" => "9D1ZJTscrr2mK4Xnxw76ltmpwnH7udeO",
"sso_okta_token" => nil,
"sso_saml_url" => nil,
"token" => "UQRM0R3bsXDpy3p6nqtjfrbjujSadaAx",
"sso_org" => nil,
"email_from" => "[email protected]"
}
Change the system settings.
@pritunl.settings.update( theme: 'dark' )
@pritunl.settings.update(
email_username: 'user1',
email_password: '12345',
email_server: 'smtp.example.com',
email_from: '[email protected]'
)
Users
Returns a list of users in an organization sorted by name.
@pritunl.user.all( organization_id: org['id'] )
[
{
"auth_type" => "local",
"status" => false,
"dns_servers" => nil,
"otp_secret" => "OPT4HTURJTW6JLQN",
"dns_mapping" => nil,
"dns_suffix" => nil,
"servers" => [
{
"status" => false,
"platform" => nil,
"server_id" => "567369be2231390ea53d76d4",
"local_address" => "10.139.82.6",
"remote_address" => "10.139.82.7",
"virt_address6" => "fd00:c0a8:e800:0:10.139.82.6",
"virt_address" => "10.139.82.6",
"name" => "server1",
"real_address" => "8.8.8.8:41536",
"connected_since" => 1388498640,
"id" => "55e9f995b0e73033d45b44da",
"device_name" => nil
}
],
"disabled" => false,
"network_links" => [],
"sso" => nil,
"bypass_secondary" => false,
"id" => "55e9f98cb0e73033d45b44d7",
"audit" => false,
"name" => "user0",
"organization_name" => "org1",
"gravatar" => true,
"otp_auth" => false,
"organization" => "55e9f7c7b0e73033d45b44d4",
"type" => "client",
"email" => "[email protected]"
}
]
Returns a user from an organization.
@pritunl.user.find( user['id'], organization_id: org['id'] )
{
"auth_type" => "local",
"dns_servers" => nil,
"otp_secret" => "OPT4HTURJTW6JLQN",
"dns_suffix" => nil,
"disabled" => true,
"bypass_secondary" => false,
"id" => "55e9f98cb0e73033d45b44d7",
"name" => "user0",
"organization_name" => "org1",
"organization" => "55e9f7c7b0e73033d45b44d4",
"type" => "client",
"email" => "[email protected]"
}
Create a new user in an organization. An array of users can be sent for bulk adding users.
@pritunl.user.create(
organization_id: org['id'],
name: 'new_user',
email: '[email protected]',
disabled: true
)
Rename or disabled an existing user in an organization. Disabling will also disconnect the user.
@pritunl.user.update( user['id'],
organization_id: org['id'],
name: 'new_name',
email: '[email protected]',
disabled: false
)
Delete an existing user in an organization, this will disconnect the user.
@pritunl.user.delete( user['id'], organization_id: org['id'] )
Generate a new two-step authentication secret for an existing user.
@pritunl.user.otp_secret( user['id'], organization_id: org['id'] )
Organizations
Returns a list of organizations on the server sorted by name.
@pritunl.organization.all
[
{
"user_count" => 512,
"id" => "55e99499b0e7300fef77e2b1",
"name" => "org1"
},
{
"user_count" => 1024,
"id" => "55e9f1d4b0e730245677dc2d",
"name" => "org2"
}
]
Returns an organization.
@pritunl.organization.find( org['id'] )
{
"user_count" => 512,
"id" => "55e99499b0e7300fef77e2b1",
"name" => "org1"
}
Create a new organization.
@pritunl.organization.create( name: 'new_org' )
Rename an existing organization.
@pritunl.organization.update( org['id'], name: 'new_name' )
Delete an existing organization.
@pritunl.organization.delete( org['id'] )
Keys
Download a users key tar archive.
@pritunl.key.download_tar( organization_id: org['id'], user_id: user['id'], path: 'output.tar' )
Download a users onc key zip archive.
@pritunl.key.download_zip( organization_id: org['id'], user_id: user['id'], path: 'output.zip' )
Generate a temporary url to download a users key archive.
@pritunl.key.temporary_url( organization_id: org['id'], user_id: user['id'] )
{
"view_url" => "/k/MjyaVvGk",
"key_url" => "/key/4f5bd04d85414e20b0a451d642dab06d.tar",
"uri_url" => "/ku/MjyaVvGk",
"key_zip_url" => "/key/4f5bd04d85414e20b0a451d642dab06d.zip",
"key_onc_url" => "/key_onc/4f5bd04d85414e20b0a451d642dab06d.zip",
"id" => "4f5bd04d85414e20b0a451d642dab06d"
}
Servers
Returns a list of servers.
@pritunl.server.all
Returns a server.
@pritunl.server.find( server['id'] )
{
"status" => "pending",
"lzo_compression" => false,
"dns_servers" => ["8.8.4.4"],
"protocol" => "udp",
"ping_interval" => 10,
"dns_mapping" => false,
"network_mode" => "tunnel",
"debug" => false,
"network_end" => nil,
"bind_address" => nil,
"link_ping_interval" => 1,
"hash" => "sha1",
"ipv6_firewall" => true,
"inter_client" => true,
"id" => "5678d5286231390ea53eda96",
"network_start" => nil,
"network" => "10.11.6.0/24",
"local_networks" => [],
"uptime" => nil,
"user_count" => 0,
"name" => "server1",
"dh_param_bits" => 2048,
"max_clients" => 2048,
"users_online" => 0,
"replica_count" => 1,
"link_ping_timeout" => 5,
"port" => 12533,
"devices_online" => 0,
"ping_timeout" => 60,
"mode" => "all_traffic",
"ipv6" => false,
"otp_auth" => false,
"jumbo_frames" => false,
"multi_device" => false,
"search_domain" => "example.com",
"cipher" => "aes256"
}
Create a new server.
@pritunl.server.create(
name: 'server1',
network: '10.11.6.0/24',
bind_address: nil,
port: 12533,
protocol: 'udp',
dh_param_bits: 2048,
mode: 'all_traffic',
network_mode: 'tunnel',
network_start: nil,
network_end: nil,
multi_device: false,
local_networks: [],
dns_servers: ['8.8.4.4'],
search_domain: 'pritunl.com',
otp_auth: false,
cipher: 'aes256',
jumbo_frames: false,
lzo_compression: false,
inter_client: true,
ping_interval: 10,
ping_timeout: 60,
max_clients: 2048,
replica_count: 1,
debug: false
)
Update an existing server.
@pritunl.server.update( server['id'], name: 'server1-rename', dns_servers: ['8.8.8.8', '8.8.4.4'] )
Delete an existing server.
@pritunl.server.delete( server['id'] )
Start, stop or restart an existing server.
@pritunl.server.start( server['id'] )
@pritunl.server.stop( server['id'] )
@pritunl.server.restart( server['id'] )
Returns a list of organizations attached to a server.
@pritunl.server.organizations( server['id'] )
[
{
"id" => "5678d0f48831390da53ef8ae",
"name" => "org1",
"server" => "5678d5286231390ea53eda96"
},
{
"id" => "5678d0f48831392ba71ad3cb",
"name" => "org2",
"server" => "5678d5286231390ea53eda96"
}
]
Attach an organization to an existing server.
@pritunl.server.attach_organization( server['id'], organization_id: org['id'] )
{
"id" => "5678d0f48831390da53ef8ae",
"name" => "org1",
"server" => "5678d5286231390ea53eda96"
}
Remove an organization from an existing server.
@pritunl.server.remove_organization( server['id'], organization_id: org['id'] )
Get the output of a server.
@pritunl.server.output( server['id'] )
{
"id" => "5678d5286231390ea53eda96",
"output" => [
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 OpenVPN 2.3.2 x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZO] [EPOLL] [PKCS11] [eurephia] [MH] [IPv6] built on Dec 1 2014",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 Control Channel Authentication: tls-auth using INLINE static key file",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 TUN/TAP device tun11 opened",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 do_ifconfig, tt->ipv6=0, tt->did_ifconfig_ipv6_setup=0",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 /sbin/ip link set dev tun11 up mtu 1500",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 /sbin/ip addr add dev tun11 10.11.6.1/24 broadcast 10.11.6.255",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 UDPv4 link local (bound): [undef]",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 UDPv4 link remote: [undef]",
"[patient-forest-4024] Mon Dec 21 23:45:15 2015 Initialization Sequence Completed"
]
}
Clear the output of a server.
@pritunl.server.clear_output( server['id'] )
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/eterry1388/pritunl_api_client.
License
The gem is available as open source under the terms of the MIT License.