ganesha

Documentation

Overview

Package ganesha is a low-level wrapper for managing a single `nfs-ganesha` process within the container.

It provides methods to Run, Close, and determine status with IsReady.

Before starting `nfs-ganesha`, `dbus-daemon` must be running in `--system` mode, and `rpcbind` must also be started. `nfs-ganesha` seems to require that `rpcbind` is running even though it is not used for NFSv4: https://github.com/nfs-ganesha/nfs-ganesha/issues/114

Administrative tasks are performed by interacting with `nfs-ganesha` over DBus. At the moment these actions include monitoring heartbeats to provide readiness status and to collect metrics. See: https://github.com/nfs-ganesha/nfs-ganesha/wiki/Dbusinterface

Index

• type AdminMgr
  • func NewAdminMgr() (*AdminMgr, error)
  • func (mgr *AdminMgr) StreamStatus(ctx context.Context, out chan bool) error
• type BasicIO
• type BasicStats
• type Client
• type ClientMgr
  • func NewClientMgr() (*ClientMgr, error)
  • func (mgr *ClientMgr) GetNFSv40IO(ipaddr string) (*BasicStats, error)
  • func (mgr *ClientMgr) GetNFSv41IO(ipaddr string) (*BasicStats, error)
  • func (mgr *ClientMgr) ShowClients() ([]Client, error)
• type ExportIOStats
• type ExportIOStatsList
• type ExportMgr
  • func NewExportMgr() (*ExportMgr, error)
  • func (mgr *ExportMgr) GetIOStats() (*ExportIOStatsList, error)
• type Ganesha
  • func New(config string) *Ganesha
  • func (g *Ganesha) Close(ctx context.Context)
  • func (g *Ganesha) IsReady(ctx context.Context) bool
  • func (g *Ganesha) Run() (<-chan error, error)
• type StatsBaseAnswer

Types

type AdminMgr

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

AdminMgr is a handle to Ganesha's management interface.

func NewAdminMgr

func NewAdminMgr() (*AdminMgr, error)

NewAdminMgr creates a new AdminMgr for interacting with Ganesha's management interface.

Requires system DBus, which must be running. Ganesha does not have to have registered yet.

func (*AdminMgr) StreamStatus

func (mgr *AdminMgr) StreamStatus(ctx context.Context, out chan bool) error

StreamStatus streams the NFS server's status to the out channel.

The status is received by watching for the server's heartbeat messages that are published on DBus and converting to bools.

Ganesha does not sent heartbeats when the server is not ready, so in practice only "alive/true" messages will be sent, and/or an error returned when the context has expired or been cancelled.

type BasicIO

type BasicIO struct {
	Requested  uint64
	Transfered uint64
	Total      uint64
	Errors     uint64
	Latency    uint64
	QueueWait  uint64
}

BasicIO stores the basic statistics for NFS operations. Each field is a counter that is reset when the NFS server is started or when the NFS server receives a request to clear the stats.

type BasicStats

type BasicStats struct {
	StatsBaseAnswer
	Read  BasicIO
	Write BasicIO
}

BasicStats is the response to IO stats call, some of the fields may not be filled depending of the call type and status.

type Client

type Client struct {
	Client   string
	NFSv3    bool
	MNTv3    bool
	NLMv4    bool
	RQUOTA   bool
	NFSv40   bool
	NFSv41   bool
	NFSv42   bool
	Plan9    bool
	LastTime unix.Timespec
}

Client Structure of the output of ShowClients dbus call.

The Client field is the internal reference for the connection, typically `::ffff:172.17.0.1`.

Whenever client traffic for a protocol is detected, the corresponding field for the protocol will be set to true. When a client has multiple mounts using different protocols, or a single export has been remounted using a different protocol, mutiple protocols will be set to true for the client.

LastTime is the timestamp when the response was generated.

type ClientMgr

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

ClientMgr is a handle to Ganesha's ClientMgr DBus object.

It's main purpose it to list clients and to retrieve per-client connection statistics.

func NewClientMgr

func NewClientMgr() (*ClientMgr, error)

NewClientMgr returns a new ClientMgr.

func (*ClientMgr) GetNFSv40IO

func (mgr *ClientMgr) GetNFSv40IO(ipaddr string) (*BasicStats, error)

GetNFSv40IO returns basic stats for the NFSv4.0 client connection.

func (*ClientMgr) GetNFSv41IO

func (mgr *ClientMgr) GetNFSv41IO(ipaddr string) (*BasicStats, error)

GetNFSv41IO returns basic stats for the NFSv4.1 client connection.

func (*ClientMgr) ShowClients

func (mgr *ClientMgr) ShowClients() ([]Client, error)

ShowClients returns Ganesha's list of client connections since the server was started.

type ExportIOStats

type ExportIOStats struct {
	ExportID uint16
	Name     string
	Read     BasicIO
	Write    BasicIO
}

ExportIOStats contains the stats for a single export.

The Name field denotes the protocol being reported.

type ExportIOStatsList

type ExportIOStatsList struct {
	StatsBaseAnswer
	Exports []ExportIOStats
}

ExportIOStatsList contains the stats for all exports.

type ExportMgr

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

ExportMgr is a handle to Ganesha's DBus ExportMgr object.

It can be used to retrieve per-export protocol statistics.

func NewExportMgr

func NewExportMgr() (*ExportMgr, error)

NewExportMgr Get a new ExportMgr

func (*ExportMgr) GetIOStats

func (mgr *ExportMgr) GetIOStats() (*ExportIOStatsList, error)

GetIOStats returns the basic IO stats for all exports.

type Ganesha

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

Ganesha manages the main nfs-ganesha process.

func New

func New(config string) *Ganesha

New creates a new nfs-ganesha process which can be Run and Closed.

func (*Ganesha) Close

func (g *Ganesha) Close(ctx context.Context)

Close sends a SIGINT to the nfs-ganesha process.

Once the process has stopped, the channel returned from Run is closed.

func (*Ganesha) IsReady

func (g *Ganesha) IsReady(ctx context.Context) bool

IsReady returns true if the nfs-ganesha is ready for operation, or false if a heartbeat was not received within the timeout period.

The heartbeat message includes a boolean status field which is returned, but will always be set to true: https://github.com/nfs-ganesha/nfs-ganesha/blob/master/src/dbus/dbus_heartbeat.c#L54

Heartbeats will not be sent when the server is unhealthy.

func (*Ganesha) Run

func (g *Ganesha) Run() (<-chan error, error)

Run starts the nfs-ganesha process, returning an immediate error and nil channel if the process cannot be started.

If the process is successfully started, the returned channel will have the exit error pushed to it (which may be any error, but exec.ExitError is returned typically.)

Once the process stops, the returned channel is closed.

type StatsBaseAnswer

type StatsBaseAnswer struct {
	Status bool
	Error  string
	Time   unix.Timespec
}

StatsBaseAnswer is the base answer to stats requests, every statistics related answer begins with this.