f5

package
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 19, 2024 License: BSD-3-Clause Imports: 17 Imported by: 0

Documentation

Overview

Package f5 provides a client for using the F5 API.

Example (Transaction) 
package main

import (
	"log"

	"github.com/e-XpertSolutions/f5-rest-client/f5"
	"github.com/e-XpertSolutions/f5-rest-client/f5/ltm"
)

func main() {
	f5Client, err := f5.NewBasicClient("https://192.168.10.40", "admin", "admin")
	if err != nil {
		log.Fatal(err)
	}
	f5Client.DisableCertCheck()

	// Start new transaction.
	tx, err := f5Client.Begin()
	if err != nil {
		log.Fatal(err)
	}

	ltmClient := ltm.New(tx)

	// Create a HTTP monitor
	log.Print("Create a HTTP monitor")

	monitorConfig := ltm.MonitorHTTPConfig{
		Name: "http_monitor_" + tx.TransactionID(),
		Send: "GET / HTTP/1.0\r\n\r\n",
		Recv: "Hello",
	}

	if err := ltmClient.MonitorHTTP().Create(monitorConfig); err != nil {
		log.Fatal(err)
	}

	// Create a Pool
	log.Print("Create a pool")

	poolConfig := ltm.Pool{
		Name:    "pool_" + tx.TransactionID(),
		Monitor: "/Common/http_monitor_" + tx.TransactionID(),
		Members: []string{"10.1.10.10:80", "10.1.10.11:80"},
	}

	if err := ltmClient.Pool().Create(poolConfig); err != nil {
		log.Fatal(err)
	}

	// Create a Virtual Server
	log.Print("Create a Virtual Server")

	vsConfig := ltm.VirtualServer{
		Name:        "vs_http_" + tx.TransactionID(),
		Destination: "10.1.20.130:80",
		IPProtocol:  "tcp",
		Pool:        "pool_" + tx.TransactionID(),
		SourceAddressTranslation: ltm.SourceAddressTranslation{
			Type: "automap",
		},
		Profiles: []string{"tcp-mobile-optimized"},
	}

	if err := ltmClient.Virtual().Create(vsConfig); err != nil {
		log.Fatal(err)
	}

	// Commit to make the changes persistent.
	if err := tx.Commit(); err != nil {
		log.Fatal(err)
	}

}

Output:

Index

Examples

Constants

View Source 
const (
	PathDownloadUCS    = "/mgmt/shared/file-transfer/ucs-downloads"
	PathDownloadImage  = "/mgmt/cm/autodeploy/software-image-downloads"
	PathDownloadQKView = "/mgmt/cm/autodeploy/qkview-downloads"
)

Paths for file download.

View Source 
const (
	PathDeviceInfo = "/mgmt/tm/cm/device"
	PathSyncStatus = "/mgmt/tm/cm/sync-status"
)

Cluster Management REST paths.

View Source 
const F5TimeLayout = "2006-01-02T15:04:05.999999999-0700"

F5TimeLayout defines the layout to use for decoding dates returned by the F5 iControl REST API.

View Source 
const MaxChunkSize = 1048576

MaxChunkSize is the maximum chunk size allowed by the iControl REST

View Source 
const (
	PathBackup = "/mgmt/tm/shared/sys/backup"
)

Backup REST paths

View Source 
const (
	PathBashCmd = "/mgmt/tm/util/bash"
)

Bash util REST path.

View Source 
const (
	PathConfigSync = "/mgmt/tm/cm/config-sync"
)
View Source 
const PathTransaction = "/mgmt/tm/transaction"

PathTransaction is the path to transaction API endpoint.

View Source 
const (
	QKViewPath = "/mgmt/cm/autodeploy/qkview"
)
View Source 
const (
	// For backward compatibility
	// DEPRECATED
	UploadRESTPath = "/mgmt/shared/file-transfer/uploads"
)

Paths for file upload.

Variables

View Source 
var (
	// Upload paths
	PathUploadImage = FileTransferPath{"/mgmt/cm/autodeploy/software-image-uploads", "/shared/images"}
	PathUploadFile  = FileTransferPath{"/mgmt/shared/file-transfer/uploads", "/var/config/rest/downloads"}
	PathUploadUCS   = FileTransferPath{"mgmt/shared/file-transfer/ucs-uploads", "/var/local/ucs"}
)

File transfer path, according to: 

https://devcentral.f5.com/s/articles/demystifying-icontrol-rest-part-5-transferring-files
View Source 
var DefaultTimeout = 5 * time.Second

DefaultTimeout defines the default timeout for HTTP clients.

View Source 
var ErrNoToken = errors.New("no token")

ErrNoToken is the error returned when the Client does not have a token.

View Source 
var ErrNoTransaction = errors.New("no active transaction")

ErrNoTransaction is the error returned when a function related to transaction management is called when there is no active transaction.

Functions

func CreateToken 

func CreateToken(baseURL, user, password, loginProvName string) (string, time.Time, error)

CreateToken creates a new token with the given baseURL, user, password and loginProvName.

func IsRequestError 

func IsRequestError(err error) bool

IsRequestError reports whether err is a RequestError.

Types

type BackupResponse 

type BackupResponse struct {
	// Unique ID to identify uniquely the backup action.
	ID string `json:"id"`

	// Name of the file in which the backup is saved to or restord from.
	File string `json:"file"`

	// Type of action performed. Possible values are:
	//    - BACKUP
	//    - RESTORE
	//    - RESTORE_WITH_NO_LICENSE
	//    - BACKUP_WITH_NO_PRIVATE_KEYS
	//    - BACKUP_WITH_ENCRYPTION
	//    - BACKUP_WITH_NO_PRIVATE_KEYS_WITH_ENCRYPTION
	//    - RESTORE_WITH_ENCRYPTION
	//    - RESTORE_WITH_NO_LICENSE_WITH_ENCRYPTION
	//    - CLEANUP
	Action string `json:"action"`

	// Status of the backup. Possible values are:
	//    - CREATED
	//    - STARTED
	//    - CANCEL_REQUESTED
	//    - CANCELED
	//    - FAILED
	//    - FINISHED
	Status string `json:"status"`
}

BackupResponse holds attributes returned by requests on the backup API.

func (BackupResponse) IsCanceled 

func (resp BackupResponse) IsCanceled() bool

IsCanceled reports whether the status is CANCELED.

func (BackupResponse) IsDone 

func (resp BackupResponse) IsDone() bool

IsDone reports whether the status indicates that the action is terminated, even if it is an error or that the task has been canceled.

func (BackupResponse) IsFailure 

func (resp BackupResponse) IsFailure() bool

IsFailure reports whether the status is FAILED.

func (BackupResponse) IsSuccess 

func (resp BackupResponse) IsSuccess() bool

IsSuccess reports whether the status is FINISHED.

type Client 

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

A Client manages communication with the F5 API.

func NewBasicClient 

func NewBasicClient(baseURL, user, password string) (*Client, error)

NewBasicClient creates a new F5 client with HTTP Basic Authentication.

baseURL is the base URL of the F5 API server.

func NewTokenClient 

func NewTokenClient(baseURL, user, password, loginProvName string) (*Client, error)

NewTokenClient creates a new F5 client with token based authentication.

baseURL is the base URL of the F5 API server.

func TokenClientConnection 

func TokenClientConnection(baseURL, token string) (*Client, error)

TokenClientConnection creates a new client with the given token.

func (*Client) Backup 

func (c *Client) Backup(filename string) (*BackupResponse, error)

Backup creates a backup remotely saved into a file named according to the provided filename.

func (*Client) Begin 

func (c *Client) Begin() (*Client, error)

Begin starts a transaction.

Example 
package main

import (
	"log"

	"github.com/e-XpertSolutions/f5-rest-client/f5"
	"github.com/e-XpertSolutions/f5-rest-client/f5/ltm"
)

func main() {
	f5Client, err := f5.NewBasicClient("https://127.0.0.1", "admin", "admin")
	if err != nil {
		log.Fatal(err)
	}
	f5Client.DisableCertCheck()

	// Start new transaction.
	tx, err := f5Client.Begin()
	if err != nil {
		log.Fatal(err)
	}

	ltmClient := ltm.New(tx)

	// Node 1
	nodeConfig := ltm.Node{
		Name:    "test-node-1",
		Address: "1.1.1.1",
	}
	if err := ltmClient.Node().Create(nodeConfig); err != nil {
		log.Fatal(err)
	}

	// Node 2
	nodeConfig = ltm.Node{
		Name:    "test-node-2",
		Address: "2.2.2.2",
	}
	if err := ltmClient.Node().Create(nodeConfig); err != nil {
		log.Fatal(err)
	}

	// Commit to make the changes persistent.
	if err := tx.Commit(); err != nil {
		log.Fatal(err)
	}
}

Output:

func (*Client) CheckAuth 

func (c *Client) CheckAuth() error

CheckAuth verifies that the credentials provided at the client initialization are correct.

func (*Client) CheckBackup 

func (c *Client) CheckBackup(id string) (*BackupResponse, error)

CheckBackup fetches the status of a backup process.

func (*Client) CheckQKView 

func (c *Client) CheckQKView(id string) (*QKViewResponse, error)

func (*Client) Commit 

func (c *Client) Commit() error

Commit commits the transaction.

func (*Client) ConfigSync 

func (c *Client) ConfigSync(opts ...ConfigSyncOption) error

ConfigSync performs the config-sync operation. It only starts the sync and does not wait for it to complete. The synchronization status must be check manually.

func (*Client) DeleteQKView 

func (c *Client) DeleteQKView(id string) (*QKViewResponse, error)

func (*Client) DisableCertCheck 

func (c *Client) DisableCertCheck()

DisableCertCheck disables certificate verification, meaning that insecure certificate will not cause any error.

func (*Client) Do 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do sends an HTTP request and returns an HTTP response. It is just a wrapper arround http.Client Do method.

Callers should close resp.Body when done reading from it.

See http package documentation for more information: 

https://golang.org/pkg/net/http/#Client.Do

func (*Client) DownloadImage 

func (c *Client) DownloadImage(w io.Writer, filename string, opts ...FileTransferOption) (n int64, err error)

DownloadImage downloads BIG-IP images from the API and writes it to w.

Download can take some time due to the size of the image files.

func (*Client) DownloadQKView 

func (c *Client) DownloadQKView(w io.Writer, filename string, opts ...FileTransferOption) (n int64, err error)

DownloadQKView downloads qkview from the API and writes it to w.

Download can take some time due to the size of the file.

func (*Client) DownloadUCS 

func (c *Client) DownloadUCS(w io.Writer, filename string, opts ...FileTransferOption) (n int64, err error)

DownloadUCS downloads an UCS file and writes its content to w.

func (*Client) Exec 

func (c *Client) Exec(cmd string) (*ExecOutput, error)

Exec executes remotely a shell command on the Big-IP.

func (*Client) ExecTMSH 

func (c *Client) ExecTMSH(cmd string) (*ExecOutput, error)

ExecTMSH executes a TMSH command on the Big-IP.

func (*Client) FailoverState 

func (c *Client) FailoverState(host, ip string) (string, error)

FailoverState returns the status of the BigIP (active, standby, forced-offline, ...).

func (*Client) GenerateQKView 

func (c *Client) GenerateQKView(filename string) (*QKViewResponse, error)

func (*Client) IsActive 

func (c *Client) IsActive(host string) bool

IsActive returns true whether the BigIP is active and the iControl REST are accessible. In case of error, false is returned.

func (*Client) ListQKViews 

func (c *Client) ListQKViews() ([]QKViewResponse, error)

func (*Client) MakeRequest 

func (c *Client) MakeRequest(method, restPath string, data interface{}) (*http.Request, error)

MakeRequest creates a request with headers appropriately set to make authenticated requests. This method must be called for every new request.

func (*Client) ModQuery 

func (c *Client) ModQuery(method, restPath string, inputData interface{}) error

ModQuery performs a modification query such as POST, PUT or DELETE.

func (*Client) ReadError 

func (c *Client) ReadError(resp *http.Response) error

ReadError checks if a HTTP response contains an error and returns it.

func (*Client) ReadQuery 

func (c *Client) ReadQuery(restPath string, outputData interface{}) error

ReadQuery performs a GET query and unmarshal the response (from JSON) into outputData.

outputData must be a pointer.

func (*Client) RestoreBackup 

func (c *Client) RestoreBackup(filename string) (*BackupResponse, error)

RestoreBackup restores a backup from a file having the provided filename and located into /var/local/ucs directory.

func (*Client) RestoreBackupWithNoLicense 

func (c *Client) RestoreBackupWithNoLicense(filename string) (*BackupResponse, error)

RestoreBackupWithNoLicense works exactly as RestoreBackup but do no check the license.

func (*Client) RevokeToken 

func (c *Client) RevokeToken() error

RevokeToken revokes the current token. If the Client has not been initialized with NewTokenClient, ErrNoToken is returned.

func (*Client) Rollback 

func (c *Client) Rollback() error

Rollback aborts the current transaction. If there is no active transaction, ErrNoTransaction is returned.

func (*Client) SendRequest 

func (c *Client) SendRequest(method, restPath string, data interface{}) (*http.Response, error)

SendRequest is a shortcut for MakeRequest() + Do() + ReadError().

func (*Client) SetHTTPClient 

func (c *Client) SetHTTPClient(client http.Client)

SetHTTPClient sets the underlying HTTP used to make requests.

func (*Client) SetTimeout 

func (c *Client) SetTimeout(timeout time.Duration)

SetTimeout sets the HTTP timeout for the underlying HTTP client.

func (*Client) SyncStatus 

func (c *Client) SyncStatus() (status string, color string, err error)

SyncStatus returns the sync status of the BIG-IP along with the status color.

func (*Client) SyncStatusDetails 

func (c *Client) SyncStatusDetails() (SyncStatusResp, error)

SyncStatusDetails returns the sync status and if it is different than "In Sync" also the Group Name that is out of sync.

func (*Client) TransactionID 

func (c *Client) TransactionID() string

TransactionID returns the ID of the current transaction. If there is no active transaction, an empty string is returned.

func (*Client) TransactionState 

func (c *Client) TransactionState() (*Transaction, error)

TransactionState returns the state of the current transaction. If there is no active transaction, ErrNoTransaction is returned.

func (*Client) UploadFile 

func (c *Client) UploadFile(r io.Reader, filename string, filesize int64, opts ...FileTransferOption) (*UploadResponse, error)

UploadFile reads the content of a file from r and uploads it to the BigIP. The uploaded file will be named according to the provided filename.

filesize must be the exact file of the file.

The file is split into small chunk, therefore this method may send multiple request.

This method returns the latest upload response received.

func (*Client) UploadImage 

func (c *Client) UploadImage(r io.Reader, filename string, filesize int64, opts ...FileTransferOption) (*UploadResponse, error)

UploadImage reads the content of an disk image from r and uploads it to the BigIP.

The uploaded image will be named according to the provided filename.

filesize must be the exact file of the file.

The file is split into small chunk, therefore this method may send multiple request.

This method returns the latest upload response received.

func (*Client) UploadUCS 

func (c *Client) UploadUCS(r io.Reader, filename string, filesize int64, opts ...FileTransferOption) (*UploadResponse, error)

UploadUCS reads the content of an UCS archive from r and uploads it to the BigIP.

The uploaded UCS archive will be named according to the provided filename.

filesize must be the exact file of the file.

The file is split into small chunk, therefore this method may send multiple request.

This method returns the latest upload response received.

func (*Client) UseProxy 

func (c *Client) UseProxy(proxy string) error

UseProxy configures a proxy to use for outbound connections

func (*Client) UseSystemProxy 

func (c *Client) UseSystemProxy() error

UseSystemProxy configures the client to use the system proxy

type ConfigSyncOption 

type ConfigSyncOption func(*ConfigSyncOptions)

ConfigSyncOption is a function prototype that sets the

func WithForceFullLoadPush 

func WithForceFullLoadPush() ConfigSyncOption

WithForceFullLoadPush sets force-full-load-push parameter to true.

func WithFromGroup 

func WithFromGroup(name string) ConfigSyncOption

WithFromGroup sets the name of from-group parameter.

func WithRecoverSync 

func WithRecoverSync() ConfigSyncOption

WithRecoverSync sets recover-sync parameter to true.

func WithToGroup 

func WithToGroup(name string) ConfigSyncOption

WithToGroup sets the name of to-group parameter.

type ConfigSyncOptions 

type ConfigSyncOptions struct {
	FromGroup         string `mapstructure:"from-group,omitempty"`
	ToGroup           string `mapstructure:"to-group,omitempty"`
	RecoverSync       bool   `mapstructure:"recover-sync,omitempty"`
	ForceFullLoadPush bool   `mapstructure:"force-full-load-push,omitempty"`
}

ConfigSyncOptions represents available parameters for config-sync query.

type ExecOutput 

type ExecOutput struct {
	Kind          string `json:"kind"`
	Command       string `json:"command"`
	CommandResult string `json:"commandResult"`
	UtilCmdArgs   string `json:"utilCmdArgs"`
}

ExecOutput represents the output returned by the API afeter having executed a bash command.

type F5Date 

type F5Date struct {
	time.Time
}

F5Date wraps time.Time in order to override the time layout used during JSON decoding.

func (*F5Date) UnmarshalJSON 

func (d *F5Date) UnmarshalJSON(b []byte) error

UnmarshalJSON overrides time.Time JSON decoding to support F5 time parsing layout.

type FileTransferOption 

type FileTransferOption func(*FileTransferOptions)

FileTransferOption is a function type to set the transfer options.

func WithRemotePath 

func WithRemotePath(path string) FileTransferOption

WithRemotePath sets the source directory on the remote F5 for file download.

func WithSFTP 

func WithSFTP(config *ssh.ClientConfig) FileTransferOption

WithSFTP sets the ssh configuration for file transfer.

func WithTarget 

func WithTarget(target FileTransferPath) FileTransferOption

WithTarget overrides the default FileTransferPath. This options has effects only on upload methods.

type FileTransferOptions 

type FileTransferOptions struct {
	UseSFTP      bool
	ClientConfig *ssh.ClientConfig
	RemotePath   string           // for download only
	Target       FileTransferPath // for upload only
}

FileTransferOptions contains SSH configuration for downloading and uploading UCS using SFTP.

type FileTransferPath 

type FileTransferPath struct {
	URI       string
	RemoteDir string
}

FileTransferPath holds the REST path and the corresponding remote directory for file transfer.

type QKViewResponse 

type QKViewResponse struct {
	// Unique ID to identify uniquely the qkview.
	ID string `json:"id"`

	// Name of the file in which the qkview is saved.
	Name string `json:"name"`

	//Status of qkview. Possible values are:
	//	- SUCCEDED
	//	- FAILED
	//	- IN_PROGRESS
	Status string `json:"status"`
}

type RequestError 

type RequestError struct {
	Code     int      `json:"code,omitempty"`
	Message  string   `json:"message,omitempty"`
	ErrStack []string `json:"errorStack,omitempty"`
}

A RequestError is returned as a HTTP Response by the F5 Big IP server in case of error.

func NewRequestError 

func NewRequestError(body io.Reader) (*RequestError, error)

NewRequestError unmarshal a RequestError from a HTTP response body.

func (RequestError) Error 

func (err RequestError) Error() string

Error implements the errors.Error interface

func (RequestError) String 

func (err RequestError) String() string

type SyncStatusResp 

type SyncStatusResp struct {
	Status    string
	Color     string
	Action    string
	GroupName string
}

SyncStatusResp contains the values obtained from the sync-status check.

type Transaction 

type Transaction struct {
	TransID          int64  `json:"transId"`
	ValidateOnly     bool   `json:"validateOnly"`
	ExecutionTimeout int64  `json:"executionTimeout"`
	SelfLink         string `json:"selfLink"`
	State            string `json:"state"`
	TimeoutSeconds   int64  `json:"timeoutSeconds"`
	AsyncExecution   bool   `json:"asynExecution"`
	FailureReason    string `json:"failureReason"`
	Kind             string `json:"kind"`
}

A Transaction holds the state of a remote transaction identified by its transaction ID.

type UploadResponse 

type UploadResponse struct {
	RemainingByteCount int64          `json:"remainingByteCount"`
	UsedChunks         map[string]int `json:"usedChunks"`
	TotalByteCount     int64          `json:"totalByteCount"`
	LocalFilePath      string         `json:"localFilePath"`
	TemporaryFilePath  string         `json:"temporaryFilePath"`
	Generation         int64          `json:"generation"`
	LastUpdateMicros   int64          `json:"lastUpdateMicros"`
}

An UploadResponse holds the responses send by the BigIP API while uploading files.

Source Files

View all Source files

Directories

Path Synopsis
Package ltm provides a REST client for the /tm/ltm F5 BigIP API.
 Package ltm provides a REST client for the /tm/ltm F5 BigIP API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.