pritunl-api-go

Pritunl API Client for Go

A Go client for the Pritunl API, allowing you to interact with Pritunl servers and perform various actions.

Getting Started

Environment Variables

Load your Pritunl API credentials as environment variables:

export PRITUNL_BASE_URL="https://vpn.domain.tld"
export PRITUNL_API_TOKEN="<PRITUNL API TOKEN>"
export PRITUNL_API_SECRET="<PRITUNL API SECRET>"

Installation

Get the Pritunl API Client for Go package/library:

go get github.com/nathanielvarona/pritunl-api-go

Usage

Initialize an API instance and call available feature functions:

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"github.com/nathanielvarona/pritunl-api-go"
)

func main() {
	// Initialize the Pritunl API client
	client, err := pritunl.NewClient()
	// Alternatively, you can initialize the client with manual arguments
	// client, err := pritunl.NewClient(&pritunl.Client{
	// 	BaseUrl:   "<PRITUNL BASE URL>",
	// 	ApiToken:  "<PRITUNL API TOKEN>",
	// 	ApiSecret: "<PRITUNL API SECRET>",
	// })
	if err != nil {
		log.Fatal(err)
	}

	// Create a context for the request
	ctx := context.Background()

	// Retrieve the server status
	status, err := client.StatusGet(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Print server status details
	fmt.Println("Server Status:")
	for _, stat := range status {
		fmt.Println("Server Version:", stat.ServerVersion)
		fmt.Println("Local Networks:", stat.LocalNetworks)
		fmt.Println("Host Online:", stat.HostsOnline)
		fmt.Println("------")
	}

	// Marshal server status to JSON
	statusBytes, err := json.MarshalIndent(status, "", "  ")
	if err != nil {
		log.Println("Error marshalling status:", err)
	} else {
		fmt.Println("Server Status in JSON:")
		fmt.Println(string(statusBytes))
	}
}

Examples

Check the _examples folder for code examples demonstrating how to use this package/library.

Contributing

We welcome your contributions to pritunl-api-go. This guide outlines the process for contributing effectively.

Fork & Pull Requests

Workflow:

1. Fork the repository: Visit the pritunl-api-go repository on GitHub and click "Fork". This creates your own copy.
2. Clone your forked repository: Use git clone to clone your forked copy to your local development environment.
3. Create a Branch: Use a descriptive branch name following the convention <type>/<descriptive-name>.
   • <type>: Choose from breaking, feature, improvement, automation, or documentation.
   • Refer to the .github/labels.yml and .github/pr-labeler.yml file for valid <type> options and label descriptions. (e.g., improvement/start-stop-a-server)
4. Make your changes: Implement your code modifications, ensuring they adhere to Go coding conventions gofmt and consider adding unit tests ^ref* for new features.
5. Commit your changes: Stage and commit your changes with clear and concise commit messages.
6. Push your branch and Create a Pull Request: Push your local branch to your forked repository on GitHub and create a pull request with a detailed description of your changes.

Additional Tips:

• ^ref* Include examples where relevant to illustrate your changes.
• Simplify your development workflow! We recommend using a Go workspace when contributing to pritunl-api-go. Go workspaces provide a clean and efficient way to manage dependencies.
  • Refer to the official guide for setting up a workspace: https://go.dev/doc/tutorial/workspaces

Rebasing and Squashing Commits

Before submitting your pull request, we recommend cleaning up your commit history to make it easier to review. This involves rebasing your branch on top of the main branch and combining your commits into a single, clear commit. Additionally, please ensure that your commit author name and email are consistent with your GitHub account, as this will help us keep a clear record of contributions.

We appreciate your contributions to the project!

By following these guidelines, you'll help us maintain a high-quality codebase and make it easier for others to contribute. Thank you for taking the time to contribute to pritunl-api-go!

Features

Core Pritunl API Client

Feature Function	Description	Status
StatusGet	Status of Pritunl Server	✅ Yes
KeyGet	Generate or Retrieve a Key for the User	✅ Yes
UserGet	Get the Information of Existing User	✅ Yes
UserCreate	Create a New User	✅ Yes
UserUpdate	Update an Existing User	✅ Yes
UserDelete	Delete an User	✅ Yes
OrganizationGet	Get the Information of Existing Org	✅ Yes
OrganizationCreate	Create a New Org	✅ Yes
OrganizationUpdate	Update an Existing Org	✅ Yes
OrganizationDelete	Delete an Org	✅ Yes
ServerGet	Get the Information of Existing Server	✅ Yes
ServerCreate	Create a New Server	✅ Yes
ServerUpdate	Update an existing Server	✅ Yes
ServerDelete	Delete a Server	✅ Yes
ServerStart	Start an existing Server	✅ Yes
ServerStop	Start an existing Server	✅ Yes
ServerRestart	Restart an existing Server	✅ Yes
ServerRouteGet	Get the Routes for a Server	✅ Yes
ServerRouteCreate	Create/Add a Server Route	✅ Yes
ServerRouteUpdate	Update a Server Route	✅ Yes
ServerRouteDelete	Remove/Delete a Server Route	✅ Yes
ServerOrgAttach	Attach an Organization for a Server	✅ Yes
ServerOrgDetach	Detach an Organization for a Server	✅ Yes
ServerHostAttach	Attach a Host for a Server	✅ Yes
ServerHostDetach	Detach a Host for a Server	✅ Yes

Future Enhancements (CLI)

1. CLI Framework: Consider using a popular framework like spf13/cobra, urfave/cli, or alecthomas/kong to simplify the command structure, argument parsing, and flag handling.
2. Build Distribution Workflow: Implement a CI/CD workflow (e.g., using GitHub Actions) to automate building and distributing the CLI tool across various platforms (Windows, macOS, Linux) and architectures (32-bit, 64-bit). This will streamline setup for users on different systems.

Alternative API Clients

• Python - Pritunl API Client for Python by @nathanielvarona
  • fork from Pritunl API client for Python 3 by @ijat
• Ruby - Pritunl API Client by @eterry1388