Documentation
¶
Overview ¶
Package f5 provides a client for using the F5 API.
Example (Transaction) ¶
package main import ( "log" "github.com/mingkyme/f5-rest-client/f5" "github.com/mingkyme/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 ¶
- Constants
- Variables
- func CreateToken(baseURL, user, password, loginProvName string) (string, time.Time, error)
- func IsRequestError(err error) bool
- type BackupResponse
- type Client
- func (c *Client) Backup(filename string) (*BackupResponse, error)
- func (c *Client) Begin() (*Client, error)
- func (c *Client) CheckAuth() error
- func (c *Client) CheckBackup(id string) (*BackupResponse, error)
- func (c *Client) CheckQKView(id string) (*QKViewResponse, error)
- func (c *Client) Commit() error
- func (c *Client) ConfigSync(opts ...ConfigSyncOption) error
- func (c *Client) DeleteQKView(id string) (*QKViewResponse, error)
- func (c *Client) DisableCertCheck()
- func (c *Client) Do(req *http.Request) (*http.Response, error)
- func (c *Client) DownloadImage(w io.Writer, filename string, opts ...FileTransferOption) (n int64, err error)
- func (c *Client) DownloadQKView(w io.Writer, filename string, opts ...FileTransferOption) (n int64, err error)
- func (c *Client) DownloadUCS(w io.Writer, filename string, opts ...FileTransferOption) (n int64, err error)
- func (c *Client) Exec(cmd string) (*ExecOutput, error)
- func (c *Client) ExecTMSH(cmd string) (*ExecOutput, error)
- func (c *Client) FailoverState(host, ip string) (string, error)
- func (c *Client) GenerateQKView(filename string) (*QKViewResponse, error)
- func (c *Client) IsActive(host string) bool
- func (c *Client) ListQKViews() ([]QKViewResponse, error)
- func (c *Client) MakeRequest(method, restPath string, data interface{}) (*http.Request, error)
- func (c *Client) ModQuery(method, restPath string, inputData interface{}) error
- func (c *Client) ReadError(resp *http.Response) error
- func (c *Client) ReadQuery(restPath string, outputData interface{}) error
- func (c *Client) RestoreBackup(filename string) (*BackupResponse, error)
- func (c *Client) RestoreBackupWithNoLicense(filename string) (*BackupResponse, error)
- func (c *Client) RevokeToken() error
- func (c *Client) Rollback() error
- func (c *Client) SendRequest(method, restPath string, data interface{}) (*http.Response, error)
- func (c *Client) SetHTTPClient(client http.Client)
- func (c *Client) SetTimeout(timeout time.Duration)
- func (c *Client) SyncStatus() (status string, color string, err error)
- func (c *Client) SyncStatusDetails() (SyncStatusResp, error)
- func (c *Client) TransactionID() string
- func (c *Client) TransactionState() (*Transaction, error)
- func (c *Client) UploadFile(r io.Reader, filename string, filesize int64, opts ...FileTransferOption) (*UploadResponse, error)
- func (c *Client) UploadImage(r io.Reader, filename string, filesize int64, opts ...FileTransferOption) (*UploadResponse, error)
- func (c *Client) UploadUCS(r io.Reader, filename string, filesize int64, opts ...FileTransferOption) (*UploadResponse, error)
- func (c *Client) UseProxy(proxy string) error
- func (c *Client) UseSystemProxy() error
- type ConfigSyncOption
- type ConfigSyncOptions
- type ExecOutput
- type F5Date
- type FileTransferOption
- type FileTransferOptions
- type FileTransferPath
- type QKViewResponse
- type RequestError
- type SyncStatusResp
- type Transaction
- type UploadResponse
Examples ¶
Constants ¶
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.
const ( PathDeviceInfo = "/mgmt/tm/cm/device" PathSyncStatus = "/mgmt/tm/cm/sync-status" )
Cluster Management REST paths.
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.
const MaxChunkSize = 1048576
MaxChunkSize is the maximum chunk size allowed by the iControl REST
const (
PathBackup = "/mgmt/tm/shared/sys/backup"
)
Backup REST paths
const (
PathBashCmd = "/mgmt/tm/util/bash"
)
Bash util REST path.
const (
PathConfigSync = "/mgmt/tm/cm/config-sync"
)
const PathTransaction = "/mgmt/tm/transaction"
PathTransaction is the path to transaction API endpoint.
const (
QKViewPath = "/mgmt/cm/autodeploy/qkview"
)
const ( // For backward compatibility // DEPRECATED UploadRESTPath = "/mgmt/shared/file-transfer/uploads" )
Paths for file upload.
Variables ¶
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
var DefaultTimeout = 5 * time.Second
DefaultTimeout defines the default timeout for HTTP clients.
var ErrNoToken = errors.New("no token")
ErrNoToken is the error returned when the Client does not have a token.
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 ¶
CreateToken creates a new token with the given baseURL, user, password and loginProvName.
func IsRequestError ¶
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 ¶
NewBasicClient creates a new F5 client with HTTP Basic Authentication.
baseURL is the base URL of the F5 API server.
func NewTokenClient ¶
NewTokenClient creates a new F5 client with token based authentication.
baseURL is the base URL of the F5 API server.
func TokenClientConnection ¶
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 ¶
Begin starts a transaction.
Example ¶
package main import ( "log" "github.com/mingkyme/f5-rest-client/f5" "github.com/mingkyme/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 ¶
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) 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 ¶
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 ¶
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 ¶
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 ¶
MakeRequest creates a request with headers appropriately set to make authenticated requests. This method must be called for every new request.
func (*Client) ReadQuery ¶
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 ¶
RevokeToken revokes the current token. If the Client has not been initialized with NewTokenClient, ErrNoToken is returned.
func (*Client) Rollback ¶
Rollback aborts the current transaction. If there is no active transaction, ErrNoTransaction is returned.
func (*Client) SendRequest ¶
SendRequest is a shortcut for MakeRequest() + Do() + ReadError().
func (*Client) SetHTTPClient ¶
SetHTTPClient sets the underlying HTTP used to make requests.
func (*Client) SetTimeout ¶
SetTimeout sets the HTTP timeout for the underlying HTTP client.
func (*Client) SyncStatus ¶
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 ¶
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) UseSystemProxy ¶
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 ¶
F5Date wraps time.Time in order to override the time layout used during JSON decoding.
func (*F5Date) UnmarshalJSON ¶
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 ¶
FileTransferPath holds the REST path and the corresponding remote directory for file transfer.
type QKViewResponse ¶
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 ¶
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.