minio/pkg/madmin/API.md

Golang Admin Client API Reference

Initialize Minio Admin Client object.

Minio

package main

import (
    "fmt"

    "github.com/minio/minio/pkg/madmin"
)

func main() {
    // Use a secure connection.
    ssl := true

    // Initialize minio client object.
    mdmClnt, err := madmin.New("your-minio.example.com:9000", "YOUR-ACCESSKEYID", "YOUR-SECRETKEY", ssl)
    if err != nil {
        fmt.Println(err)
        return
    }

    // Fetch service status.
    st, err := mdmClnt.ServiceStatus()
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Printf("%#v\n", st)
}

Service operations	LockInfo operations	Healing operations	Config operations	Misc
ServiceStatus	ListLocks	Heal	GetConfig	SetCredentials
ServiceSendAction	ClearLocks		SetConfig

1. Constructor

New(endpoint string, accessKeyID string, secretAccessKey string, ssl bool) (*AdminClient, error)

Initializes a new admin client object.

Parameters

Param	Type	Description
endpoint	string	Minio endpoint.
accessKeyID	string	Access key for the object storage endpoint.
secretAccessKey	string	Secret key for the object storage endpoint.
ssl	bool	Set this value to 'true' to enable secure (HTTPS) access.

2. Admin API Version

VersionInfo() (AdminAPIVersionInfo, error)

Fetch server's supported Administrative API version.

Example

	info, err := madmClnt.VersionInfo()
	if err != nil {
		log.Fatalln(err)
	}
	log.Printf("%s\n", info.Version)

3. Service operations

ServiceStatus() (ServiceStatusMetadata, error)

Fetch service status, replies disk space used, backend type and total disks offline/online (applicable in distributed mode).

Param	Type	Description
serviceStatus	ServiceStatusMetadata	Represents current server status info in following format:

Param	Type	Description
st.ServerVersion.Version	string	Server version.
st.ServerVersion.CommitID	string	Server commit id.
st.StorageInfo.Total	int64	Total disk space.
st.StorageInfo.Free	int64	Free disk space.
st.StorageInfo.Backend	struct{}	Represents backend type embedded structure.

Param	Type	Description
backend.Type	BackendType	Type of backend used by the server currently only FS or Erasure.
backend.OnlineDisks	int	Total number of disks online (only applies to Erasure backend), is empty for FS.
backend.OfflineDisks	int	Total number of disks offline (only applies to Erasure backend), is empty for FS.
backend.StandardSCParity	int	Parity disks set for standard storage class, is empty for FS.
backend.RRSCParity	int	Parity disks set for reduced redundancy storage class, is empty for FS.

Example

   st, err := madmClnt.ServiceStatus()
   if err != nil {
   	log.Fatalln(err)
   }
   log.Printf("%#v\n", st)

ServiceSendAction(act ServiceActionValue) (error)

Sends a service action command to service - possible actions are restarting and stopping the server.

Example

   // to restart
   st, err := madmClnt.ServiceSendAction(ServiceActionValueRestart)
   // or to stop
   // st, err := madmClnt.ServiceSendAction(ServiceActionValueStop)
   if err != nil {
   	log.Fatalln(err)
   }
   log.Printf("Success")

4. Info operations

ServerInfo() ([]ServerInfo, error)

Fetch all information for all cluster nodes, such as uptime, region, network statistics, etc..

Example

   serversInfo, err := madmClnt.ServerInfo()
   if err != nil {
   	log.Fatalln(err)
   }

   for _, peerInfo := range serversInfo {
   	log.Printf("Node: %s, Info: %v\n", peerInfo.Addr, peerInfo.Data)
   }

5. Lock operations

ListLocks(bucket, prefix string, duration time.Duration) ([]VolumeLockInfo, error)

If successful returns information on the list of locks held on bucket matching prefix for longer than duration seconds.

Example

    volLocks, err := madmClnt.ListLocks("mybucket", "myprefix", 30 * time.Second)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("List of locks: ", volLocks)

ClearLocks(bucket, prefix string, duration time.Duration) ([]VolumeLockInfo, error)

If successful returns information on the list of locks cleared on bucket matching prefix for longer than duration seconds.

Example

    volLocks, err := madmClnt.ClearLocks("mybucket", "myprefix", 30 * time.Second)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("List of locks cleared: ", volLocks)

6. Heal operations

Heal(bucket, prefix string, healOpts HealOpts, clientToken string, forceStart bool) (start HealStartSuccess, status HealTaskStatus, err error)

Start a heal sequence that scans data under given (possible empty) bucket and prefix. The recursive bool turns on recursive traversal under the given path. dryRun does not mutate on-disk data, but performs data validation. incomplete enables healing of multipart uploads that are in progress. removeBadFiles removes unrecoverable files. statisticsOnly turns off detailed heal-operations reporting in the status call.

Two heal sequences on overlapping paths may not be initiated.

The progress of a heal should be followed using the HealStatus API. The server accumulates results of the heal traversal and waits for the client to receive and acknowledge them using the status API. When the statistics-only option is set, the server only maintains aggregates statistics - in this case, no acknowledgement of results is required.

Example

    healPath, err := madmClnt.HealStart("", "", true, false, true, false, false)
    if err != nil {
        log.Fatalln(err)
    }
    log.Printf("Heal sequence started at %s", healPath)

HealTaskStatus structure

Param	Type	Description
s.Summary	string	Short status of heal sequence
s.FailureDetail	string	Error message in case of heal sequence failure
s.HealSettings	HealOpts	Contains the booleans set in the HealStart call
s.Items	[]HealResultItem	Heal records for actions performed by server
s.Statistics	HealStatistics	Aggregate of heal records from beginning

HealResultItem structure

Param	Type	Description
ResultIndex	int64	Index of the heal-result record
Type	HealItemType	Represents kind of heal operation in the heal record
Bucket	string	Bucket name
Object	string	Object name
Detail	string	Details about heal operation
DiskInfo.AvailableOn	[]int	List of disks on which the healed entity is present and healthy
DiskInfo.HealedOn	[]int	List of disks on which the healed entity was restored

HealStatistics structure

Most parameters represent the aggregation of heal operations since the start of the heal sequence.

Param	Type	Description
NumDisks	int	Number of disks configured in the backend
NumBucketsScanned	int64	Number of buckets scanned
BucketsMissingByDisk	map[int]int64	Map of disk to number of buckets missing
BucketsAvailableByDisk	map[int]int64	Map of disk to number of buckets available
BucketsHealedByDisk	map[int]int64	Map of disk to number of buckets healed on
NumObjectsScanned	int64	Number of objects scanned
NumUploadsScanned	int64	Number of uploads scanned
ObjectsByAvailablePC	map[int64]	Map of available part counts (after heal) to number of objects
ObjectsByHealedPC	map[int64]	Map of healed part counts to number of objects
ObjectsMissingByDisk	map[int64]	Map of disk number to number of objects with parts missing on that disk
ObjectsAvailableByDisk	map[int64]	Map of disk number to number of objects available on that disk
ObjectsHealedByDisk	map[int64]	Map of disk number to number of objects healed on that disk

Example

    res, err := madmClnt.HealStatus("", "")
    if err != nil {
        log.Fatalln(err)
    }
    log.Printf("Heal sequence status data %#v", res)

7. Config operations

GetConfig() ([]byte, error)

Get config.json of a minio setup.

Example

    configBytes, err := madmClnt.GetConfig()
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    // Pretty-print config received as json.
    var buf bytes.Buffer
    err = json.Indent(buf, configBytes, "", "\t")
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    log.Println("config received successfully: ", string(buf.Bytes()))

SetConfig(config io.Reader) (SetConfigResult, error)

Set config.json of a minio setup and restart setup for configuration change to take effect.

Param	Type	Description
st.Status	bool	true if set-config succeeded, false otherwise.
st.NodeSummary.Name	string	Network address of the node.
st.NodeSummary.ErrSet	bool	Bool representation indicating if an error is encountered with the node.
st.NodeSummary.ErrMsg	string	String representation of the error (if any) on the node.

Example

    config := bytes.NewReader([]byte(`config.json contents go here`))
    result, err := madmClnt.SetConfig(config)
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    var buf bytes.Buffer
    enc := json.NewEncoder(&buf)
    enc.SetEscapeHTML(false)
    enc.SetIndent("", "\t")
    err = enc.Encode(result)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("SetConfig: ", string(buf.Bytes()))

8. Misc operations

SetCredentials() error

Set new credentials of a Minio setup.

Example

    err = madmClnt.SetCredentials("YOUR-NEW-ACCESSKEY", "YOUR-NEW-SECRETKEY")
    if err != nil {
            log.Fatalln(err)
    }
    log.Println("New credentials successfully set.")