api

Documentation

Index

• func GetMinTLSVersion(version string) (uint16, error)
• type AuthenticationResponseBody
• type AuthenticationResponseCapabilities
• type AuthenticationResponseData
• type Authenticator
  • func NewTicketAuthenticator(creds TicketCredentials) (Authenticator, error)
  • func NewTokenAuthenticator(toc TokenCredentials) (Authenticator, error)
  • func NewUserAuthenticator(creds UserCredentials, conn *Connection) Authenticator
• type Client
  • func NewClient(creds Credentials, conn *Connection) (Client, error)
• type Connection
  • func NewConnection(endpoint string, insecure bool, minTLS string) (*Connection, error)
• type Credentials
  • func NewCredentials(username, password, otp, apiToken, authTicket, csrfPreventionToken string) (Credentials, error)
• type Error
  • func (err Error) Error() string
• type ErrorResponseBody
• type FileUploadRequest
• type HTTPError
  • func (err HTTPError) Error() string
• type MultiPartData
• type TicketCredentials
• type TokenCredentials
• type UserCredentials

Functions

func GetMinTLSVersion

func GetMinTLSVersion(version string) (uint16, error)

GetMinTLSVersion returns the minimum TLS version constant for the given string. If the string is empty, the default TLS version is returned. For unsupported TLS versions, an error is returned.

Types

type AuthenticationResponseBody

type AuthenticationResponseBody struct {
	Data *AuthenticationResponseData `json:"data,omitempty"`
}

AuthenticationResponseBody contains the body from an authentication response.

type AuthenticationResponseCapabilities

type AuthenticationResponseCapabilities struct {
	Access     *types.CustomPrivileges `json:"access,omitempty"`
	Datacenter *types.CustomPrivileges `json:"dc,omitempty"`
	Mapping    *types.CustomPrivileges `json:"mapping,omitempty"`
	Nodes      *types.CustomPrivileges `json:"nodes,omitempty"`
	SDN        *types.CustomPrivileges `json:"sdn,omitempty"`
	Storage    *types.CustomPrivileges `json:"storage,omitempty"`
	VMs        *types.CustomPrivileges `json:"vms,omitempty"`
}

AuthenticationResponseCapabilities contains the supported capabilities for a session.

type AuthenticationResponseData

type AuthenticationResponseData struct {
	ClusterName         *string                             `json:"clustername,omitempty"`
	CSRFPreventionToken *string                             `json:"CSRFPreventionToken,omitempty"`
	Capabilities        *AuthenticationResponseCapabilities `json:"cap,omitempty"`
	Ticket              *string                             `json:"ticket,omitempty"`
	Username            string                              `json:"username"`
}

AuthenticationResponseData contains the data from an authentication response.

type Authenticator

type Authenticator interface {
	// IsRoot returns true if the authenticator is configured to use the root
	IsRoot() bool

	// IsRootTicket returns true if the authenticator is configured to use the root directly using a login ticket.
	// (root using token is weaker, cannot change VM arch)
	IsRootTicket() bool

	// AuthenticateRequest adds authentication data to a new request.
	AuthenticateRequest(ctx context.Context, req *http.Request) error
}

Authenticator is an interface for adding authentication data to a request. The authenticator is also aware of the authentication context, e.g. if it is configured to use the root user.

func NewTicketAuthenticator

func NewTicketAuthenticator(creds TicketCredentials) (Authenticator, error)

NewTicketAuthenticator returns a new ticket authenticator.

func NewTokenAuthenticator

func NewTokenAuthenticator(toc TokenCredentials) (Authenticator, error)

NewTokenAuthenticator creates a new authenticator that uses a PVE API Token for authentication.

func NewUserAuthenticator

func NewUserAuthenticator(creds UserCredentials, conn *Connection) Authenticator

NewUserAuthenticator creates a new authenticator that uses a username and password for authentication.

type Client

type Client interface {
	// DoRequest performs a request against the Proxmox API.
	DoRequest(
		ctx context.Context,
		method, path string,
		requestBody, responseBody interface{},
	) error

	// ExpandPath expands a path relative to the client's base path.
	// For example, if the client is configured for a VM and the
	// path is "firewall/options", the returned path will be
	// "/nodes/<node>/qemu/<vmid>/firewall/options".
	ExpandPath(path string) string

	// IsRoot returns true if the client is configured with the root user.
	IsRoot() bool

	// IsRootTicket returns true if the authenticator is configured to use the root directly using a login ticket.
	// (root using token is weaker, cannot change VM arch)
	IsRootTicket() bool

	// HTTP returns a lower-level HTTP client.
	HTTP() *http.Client
}

Client is an interface for performing requests against the Proxmox API.

func NewClient

func NewClient(creds Credentials, conn *Connection) (Client, error)

NewClient creates and initializes a VirtualEnvironmentClient instance.

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

Connection represents a connection to the Proxmox Virtual Environment API.

func NewConnection

func NewConnection(endpoint string, insecure bool, minTLS string) (*Connection, error)

NewConnection creates and initializes a Connection instance.

type Credentials

type Credentials struct {
	UserCredentials   *UserCredentials
	TokenCredentials  *TokenCredentials
	TicketCredentials *TicketCredentials
}

Credentials contains the credentials for authenticating with the Proxmox VE API.

func NewCredentials

func NewCredentials(username, password, otp, apiToken, authTicket, csrfPreventionToken string) (Credentials, error)

NewCredentials creates a new set of credentials for authenticating with the Proxmox VE API. The order of precedence is: 1. API token 2. Ticket 3. User credentials.

type Error

type Error string

Error is a sentinel error type for API errors.

const ErrNoDataObjectInResponse Error = "the server did not include a data object in the response"

ErrNoDataObjectInResponse is returned when the server does not include a data object in the response.

const ErrResourceDoesNotExist Error = "the requested resource does not exist"

ErrResourceDoesNotExist is returned when the requested resource does not exist.

func (Error) Error

func (err Error) Error() string

type ErrorResponseBody

type ErrorResponseBody struct {
	Data   *string            `json:"data"`
	Errors *map[string]string `json:"errors"`
}

ErrorResponseBody contains the body of an error response.

type FileUploadRequest

type FileUploadRequest struct {
	ContentType string
	FileName    string
	File        *os.File
	// Will be handled as unsigned 32-bit integer since the underlying type of os.FileMode is the same, but must be parsed
	// as string due to the conversion of the octal format.
	// References:
	//   1. https://en.wikipedia.org/wiki/Chmod#Special_modes
	Mode string
}

FileUploadRequest is a request for uploading a file.

type HTTPError

type HTTPError struct {
	Code    int
	Message string
}

HTTPError is a generic error type for HTTP errors.

func (HTTPError) Error

func (err HTTPError) Error() string

type MultiPartData

type MultiPartData struct {
	Boundary string
	Reader   io.Reader
	Size     *int64
}

MultiPartData enables multipart uploads in DoRequest.

type TicketCredentials

type TicketCredentials struct {
	AuthTicket          string
	CSRFPreventionToken string
}

TicketCredentials contains the auth ticket and CSRF prevention token for authenticating with the Proxmox VE API.

type TokenCredentials

type TokenCredentials struct {
	APIToken string
}

TokenCredentials contains the API token for authenticating with the Proxmox VE API.

type UserCredentials

type UserCredentials struct {
	Username string
	Password string
	OTP      string
}

UserCredentials contains the username, password, and OTP for authenticating with the Proxmox VE API.