smb

package
v0.38.0 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package smb from common/admin contains a set of APIs used to interact with and administer SMB support for ceph clusters.

The Ceph smb mgr module is based on the concept of resources. Resource descriptions are used to create, update, or delete configuration state in the Ceph cluster and the Ceph cluster will attempt to configure SMB Servers based on these resources.

Resource types include Cluster, JoinAuth, UsersAndGroups, and Share. To modify the state on the Ceph cluster use the Apply function. To query the state of the resources on the Ceph cluster use the Show function. Resources that are to be deleted should have an Intent value of Removed. Resources being updated or created must have an Intent value of Present.

Index

Constants

View Source 
const (
	// Present resources will be created or updated.
	Present = Intent("present")
	// Removed resources will be removed or ignored.
	Removed = Intent("removed")
)
View Source 
const (
	// ClusterType resources represent SMB clusters.
	ClusterType = ResourceType("ceph.smb.cluster")
	// ShareType resources represent SMB shares.
	ShareType = ResourceType("ceph.smb.share")
	// JoinAuthType resources contain information used to join a domain.
	JoinAuthType = ResourceType("ceph.smb.join.auth")
	// UsersAndGroupsType resources contain data used to define users and groups.
	UsersAndGroupsType = ResourceType("ceph.smb.usersgroups")
	// TLSCredentialType resources contain data used to establish TLS
	// secured network connections.
	TLSCredentialType = ResourceType("ceph.smb.tls.credential")
)
View Source 
const (
	// ActiveDirectoryAuth indicates a cluster will use an active directory domain.
	ActiveDirectoryAuth = ClusterAuthMode("active-directory")
	// UserAuth indicates a cluster will use locally defined users and groups.
	UserAuth = ClusterAuthMode("user")
)
View Source 
const (
	// DefaultClustering indicates SMB clustering should be enabled based on
	// the placement value.
	DefaultClustering = Clustering("default")
	// NeverClustering indicates SMB clustering should never be enabled.
	NeverClustering = Clustering("never")
	// AlwaysClustering indicates SMB clustering should always be enabled.
	AlwaysClustering = Clustering("always")
)
View Source 
const (
	// UserAccess indicates a share login control applies to a user.
	UserAccess = AccessCategory("user")
	// GroupAccess indicates a share login control applies to a group.
	GroupAccess = AccessCategory("group")
)
View Source 
const (
	// ReadAccess grants read-only access to a share.
	ReadAccess = AccessMode("read")
	// ReadWriteAccess grants read-write access to a share.
	ReadWriteAccess = AccessMode("read-write")
	// AdminAccess grants administrative access to a share.
	AdminAccess = AccessMode("admin")
	// NoneAccess denies access to a share.
	NoneAccess = AccessMode("none")
)
View Source 
const (
	// SambaVFSProvider sets the default VFS based provider.
	SambaVFSProvider = CephFSProvider("samba-vfs")
	// SambaVFSNewProvider sets the new Ceph module VFS based provider.
	SambaVFSNewProvider = CephFSProvider("samba-vfs/new")
	// SambaVFSClassicProvider sets the older Ceph module VFS based provider.
	SambaVFSClassicProvider = CephFSProvider("samba-vfs/classic")
	// SambaVFSProxiedProvider sets the new Ceph module VFS based provider with CephFS proxy server support.
	SambaVFSProxiedProvider = CephFSProvider("samba-vfs/proxied")
)
View Source 
const (
	// PasswordFilterUnset specifies no password filter.
	PasswordFilterUnset = PasswordFilter("")
	// PasswordFilterNone specifies no password filtering should be done.
	PasswordFilterNone = PasswordFilter("none")
	// PasswordFilterBase64 specifies passwords should be converted from/to
	// base64 encoding.
	PasswordFilterBase64 = PasswordFilter("base64")
	// PasswordFilterHidden specifies passwords should be replaced by opaque
	// placeholder values.
	PasswordFilterHidden = PasswordFilter("hidden")
)
View Source 
const (
	// SMBService represents the core smb network file system service.
	SMBService = Service("smb")
	// SMBMetricsService represents the prometheus style metrics service.
	SMBMetricsService = Service("smbmetrics")
	// CTDBService represents the ctdb service used to coordinate clusters.
	CTDBService = Service("ctdb")
	// RemoteControlService represents a cloud compatible remote control
	// service (based on gRPC).
	RemoteControlService = Service("remote-control")
)
View Source 
const (
	// ResourceSource indicates that another resource is being referenced.
	ResourceSource = SourceType("resource")
)

Variables

View Source 
var ErrUnknownResourceType = errors.New("unknown resource type")

ErrUnknownResourceType indicates that JSON values contained a resource type value unknown to this library.

Functions

func ValidateResources 

func ValidateResources(resources []Resource) error

ValidateResources returns an error if any resource in the supplied slice is invalid. It returns nil if all resources are valid. The first invalid resource will be identified and described in the resulting error.

Types

type AccessCategory 

type AccessCategory string

AccessCategory determines if share login controls applies to a user or group.

type AccessMode 

type AccessMode string

AccessMode determines what kind of access a share login control will grant.

type Admin 

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

Admin is used to administer ceph smb features.

func NewFromConn 

func NewFromConn(conn Commander) *Admin

NewFromConn creates an new management object from a preexisting rados connection. The existing connection can be rados.Conn or any type implementing the RadosCommander interface.

func (*Admin) Apply 

func (a *Admin) Apply(resources []Resource, opts *ApplyOptions) (
	ResultGroup, error)

Apply changes to the resource descriptions stored on the Ceph cluster. Supply one or more Resource objects in the slice and these resources will be created, updated, or removed based on the Resource's parameters. An Intent() of Present will create or update a resource. An Intent() of Removed will remove a matching resource or be a no-op if nothing is matched. The opts value can be nil for default behavior or supplied to customize the way the command processes inputs and outputs. Currently, the password values supplied in the objects and returned in the result can be filtered depending on the fields in the ApplyOptions structure.

Similar To: 

ceph smb apply -i -

func (*Admin) RemoveCluster 

func (a *Admin) RemoveCluster(clusterID string) error

RemoveCluster will remove a Cluster resource with a matching ID value from the Ceph cluster. This is a convenience function that creates a Cluster resource to remove and then applies it in one step.

func (*Admin) RemoveJoinAuth 

func (a *Admin) RemoveJoinAuth(authID string) error

RemoveJoinAuth will remove a JoinAuth resource with a matching ID value from the Ceph cluster. This is a convenience function that creates a JoinAuth resource to remove and then applies it in one step.

func (*Admin) RemoveShare 

func (a *Admin) RemoveShare(clusterID, shareID string) error

RemoveShare will remove a Share resource with matching ID values from the Ceph cluster. This is a convenience function that creates a Share resource to remove and then applies it in one step.

func (*Admin) RemoveUsersAndGroups 

func (a *Admin) RemoveUsersAndGroups(ugID string) error

RemoveUsersAndGroups will remove a UsersAndGroups resource with a matching ID value from the Ceph cluster. This is a convenience function that creates a UsersAndGroups resource to remove and then applies it in one step.

func (*Admin) Show 

func (a *Admin) Show(refs []ResourceRef, opts *ShowOptions) (
	[]Resource, error)

Show smb module resource descriptions stored on the Ceph cluster. If any values are provided in the refs slice, the function will query only resources matching those references. These may be all matching resources of a type or more specific references with IDs. The opts value can be nil for default behavior or supplied to customize the query results. Currently, ShowOptions can be used to filter password values.

Similar To: 

ceph smb show

type ApplyOptions 

type ApplyOptions struct {
	// PasswordFilter can be used to filter/obfuscate password values
	// sent to the Ceph cluster.
	PasswordFilter PasswordFilter
	// PasswordFilterOut can be used to filter/obfuscate password values
	// returned from the Ceph cluster.
	PasswordFilterOut PasswordFilter
}

ApplyOptions controls optional behavior of the Apply function.

type CephFSProvider 

type CephFSProvider string

CephFSProvider indicates what method will be used to bridge smb services to CephFS.

type CephFSSource 

type CephFSSource struct {
	Volume         string         `json:"volume"`
	SubVolumeGroup string         `json:"subvolumegroup,omitempty"`
	SubVolume      string         `json:"subvolume,omitempty"`
	Path           string         `json:"path"`
	Provider       CephFSProvider `json:"provider,omitempty"`
}

CephFSSource defines parameters that connect an SMB Share to a path or subvolume in CephFS.

type ChildResourceID 

type ChildResourceID struct {
	ResourceType ResourceType
	ParentID     string
	ID           string
}

ChildResourceID refers to a resource via its ResourceType value, the ID of a parent resource (typically a cluster) and a string ID for the child.

func (ChildResourceID) String 

func (c ChildResourceID) String() string

String returns a string value referring to a child resource ID.

func (ChildResourceID) Type 

func (c ChildResourceID) Type() ResourceType

Type returns a ResourceType value.

type Cluster 

type Cluster struct {
	IntentValue       Intent            `json:"intent"`
	ClusterID         string            `json:"cluster_id"`
	AuthMode          ClusterAuthMode   `json:"auth_mode"`
	DomainSettings    *DomainSettings   `json:"domain_settings,omitempty"`
	UserGroupSettings []UserGroupSource `json:"user_group_settings,omitempty"`
	CustomDNS         []string          `json:"custom_dns,omitempty"`
	Placement         Placement         `json:"placement,omitempty"`
	Clustering        Clustering        `json:"clustering,omitempty"`
	PublicAddrs       []PublicAddress   `json:"public_addrs,omitempty"`
}

Cluster configures an SMB Cluster resource that is managed within a Ceph cluster.

func NewActiveDirectoryCluster 

func NewActiveDirectoryCluster(
	clusterID string, realm string, ids ...string) *Cluster

NewActiveDirectoryCluster returns a new Cluster with default values set to create/update a cluster with active directory authentication. In addition to the cluster name, this function accepts the name of the domain/realm and zero or more ID values naming ceph.smb.join.auth resources.

func NewClusterToRemove 

func NewClusterToRemove(clusterID string) *Cluster

NewClusterToRemove return a new Cluster with default values set to remove a cluster from management.

func NewUserCluster 

func NewUserCluster(clusterID string, ids ...string) *Cluster

NewUserCluster returns a new Cluster with default values set to create/update a cluster with local users-and-groups defined. In addition to the cluster name, this function accepts zero or more ID values naming ceph.smb.usersgroups resources.

func (*Cluster) Identity 

func (cluster *Cluster) Identity() ResourceRef

Identity returns a ResourceRef identifying this cluster.

func (*Cluster) Intent 

func (cluster *Cluster) Intent() Intent

Intent controls if a resource is to be created/updated or removed.

func (*Cluster) MarshalJSON 

func (cluster *Cluster) MarshalJSON() ([]byte, error)

MarshalJSON supports marshalling a cluster to JSON.

func (*Cluster) SetPlacement 

func (cluster *Cluster) SetPlacement(p Placement) *Cluster

SetPlacement modifies a cluster's placement settings.

func (*Cluster) Type 

func (*Cluster) Type() ResourceType

Type returns a ResourceType value.

func (*Cluster) Validate 

func (cluster *Cluster) Validate() error

Validate returns an error describing an issue with the resource or nil if the resource object is valid.

type ClusterAuthMode 

type ClusterAuthMode string

ClusterAuthMode indicates how a Cluster should authenticate users.

type Clustering 

type Clustering string

Clustering indicates how an abstract cluster should be managed.

type Commander 

type Commander interface {
	ccom.RadosBufferCommander
}

Commander interface supports sending commands to Ceph.

type DomainSettings 

type DomainSettings struct {
	// Realm identifies the AD/Kerberos Realm to use.
	Realm string `json:"realm"`
	// JoinSources should contain one or more JoinAuthSource that
	// the cluster may use to join a domain.
	JoinSources []JoinAuthSource `json:"join_sources"`
}

DomainSettings are used to configure domain related settings for a cluster using active directory authentication.

type GroupInfo 

type GroupInfo struct {
	Name string `json:"name"`
}

GroupInfo defines a group managed by an SMB server instance.

type Intent 

type Intent string

Intent indicates how a resource description should be processed.

type JoinAuth 

type JoinAuth struct {
	IntentValue     Intent          `json:"intent"`
	AuthID          string          `json:"auth_id"`
	Auth            *JoinAuthValues `json:"auth,omitempty"`
	LinkedToCluster string          `json:"linked_to_cluster,omitempty"`
}

JoinAuth is a resource containing the parameters needed to join an SMB server to a domain.

func NewJoinAuth 

func NewJoinAuth(authID string) *JoinAuth

NewJoinAuth returns a new JoinAuth with default values.

func NewJoinAuthToRemove 

func NewJoinAuthToRemove(authID string) *JoinAuth

NewJoinAuthToRemove returns a new JoinAuth with default values set to remove the join auth resource from management.

func NewLinkedJoinAuth 

func NewLinkedJoinAuth(cluster *Cluster) *JoinAuth

NewLinkedJoinAuth returns a new JoinAuth with default values that link the resource to a particular cluster. Linked resources can only be used by the cluster they link to and are automatically deleted when the linked cluster is deleted.

func (*JoinAuth) Identity 

func (ja *JoinAuth) Identity() ResourceRef

Identity returns a ResourceRef identifying this joinauth resource.

func (*JoinAuth) Intent 

func (ja *JoinAuth) Intent() Intent

Intent controls if a resource is to be created/updated or removed.

func (*JoinAuth) MarshalJSON 

func (ja *JoinAuth) MarshalJSON() ([]byte, error)

MarshalJSON supports marshalling a cluster to JSON.

func (*JoinAuth) SetAuth 

func (ja *JoinAuth) SetAuth(un, pw string) *JoinAuth

SetAuth modifies a JoinAuth's authentication values.

func (*JoinAuth) Type 

func (*JoinAuth) Type() ResourceType

Type returns a ResourceType value.

func (*JoinAuth) Validate 

func (ja *JoinAuth) Validate() error

Validate returns an error describing an issue with the resource or nil if the resource object is valid.

type JoinAuthSource 

type JoinAuthSource struct {
	SourceType SourceType `json:"source_type"`
	Ref        string     `json:"ref"`
}

JoinAuthSource identifies a Join Auth resource that will be used as a source of authentication parameters to join a cluster to a domain.

type JoinAuthValues 

type JoinAuthValues struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

JoinAuthValues contains the username and password an SMB server will use to join a domain.

type PasswordFilter 

type PasswordFilter string

PasswordFilter allows password values to be hidden or obfuscated when sent to or fetched from the smb module.

type Placement 

type Placement map[string]any

Placement is passed to cephadm to determine where cluster services will be run.

func SimplePlacement 

func SimplePlacement(count int, label string) Placement

SimplePlacement returns a placement with common placement parameters - count and label - specified.

type PublicAddress 

type PublicAddress struct {
	Address     string
	Destination []string
}

PublicAddress used by a cluster with integrated Samba clustering enabled.

type Resource 

type Resource interface {
	// Type returns the ResourceType enum value for the resource.
	Type() ResourceType
	// Identity returns a resource reference for the resource.
	Identity() ResourceRef
	// Intent returns the intent value for the resource.
	Intent() Intent
	// Validate returns an error if the resource is not well-formed or
	// incomplete.
	Validate() error
}

Resource is an interface provided for working with abstract resource description structures in the Ceph smb module.

type ResourceID 

type ResourceID struct {
	ResourceType ResourceType
	ID           string
}

ResourceID refers to a resource via its ResourceType value and a string ID.

func (ResourceID) String 

func (r ResourceID) String() string

String returns a string value referring to a resource ID.

func (ResourceID) Type 

func (r ResourceID) Type() ResourceType

Type returns a ResourceType value.

type ResourceRef 

type ResourceRef interface {
	Type() ResourceType
	String() string
}

ResourceRef provides a structured interface to refer to resources.

type ResourceType 

type ResourceType string

ResourceType values are used to identify the type of a resource.

func (ResourceType) String 

func (rt ResourceType) String() string

String returns a string value referring to a resource.

func (ResourceType) Type 

func (rt ResourceType) Type() ResourceType

Type returns a ResourceType value.

type Result 

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

Result represents the result of applying a new/changed resource.

func (*Result) Dump 

func (r *Result) Dump() map[string]any

Dump additional fields returned with the result.

func (*Result) Error 

func (r *Result) Error() string

Error supports treating a failed result as a Go error.

func (*Result) Message 

func (r *Result) Message() string

Message returns an optional string describing the modification state.

func (*Result) Ok 

func (r *Result) Ok() bool

Ok returns true if the resource modification was a success.

func (*Result) Resource 

func (r *Result) Resource() Resource

Resource returns the resource changed.

func (*Result) State 

func (r *Result) State() string

State returns a short string describing the state of the resource.

func (*Result) UnmarshalJSON 

func (r *Result) UnmarshalJSON(data []byte) error

UnmarshalJSON support unmarshalling JSON to a Result.

type ResultGroup 

type ResultGroup struct {
	Success bool      `json:"success"`
	Results []*Result `json:"results"`
}

ResultGroup contains a series of Results and summarizes if a modifcation was a success overall.

func (ResultGroup) Error 

func (rgroup ResultGroup) Error() string

Error supports treating a failed ResultGroup as a Go error.

func (ResultGroup) ErrorResults 

func (rgroup ResultGroup) ErrorResults() []*Result

ErrorResults returns a slice of results containing items that were not successful.

func (ResultGroup) Ok 

func (rgroup ResultGroup) Ok() bool

Ok returns true if all the resource modifications were successful.

type Service added in v0.37.0 

type Service string

Service names particular network services provided by an ceph smb cluster.

type Share 

type Share struct {
	IntentValue    Intent        `json:"intent"`
	ClusterID      string        `json:"cluster_id"`
	ShareID        string        `json:"share_id"`
	Name           string        `json:"name"`
	ReadOnly       bool          `json:"readonly"`
	Browseable     bool          `json:"browseable"`
	CephFS         *CephFSSource `json:"cephfs,omitempty"`
	RestrictAccess bool          `json:"restrict_access"`
	LoginControl   []ShareAccess `json:"login_control,omitempty"`
}

Share is a resource representing SMB Shares that will be configured on the SMB servers hosted in the Ceph cluster.

func NewShare 

func NewShare(clusterID, shareID string) *Share

NewShare returns a new Share resource object with default values.

func NewShareToRemove 

func NewShareToRemove(clusterID, shareID string) *Share

NewShareToRemove returns a new Share resource object with default values set to remove the share from management.

func (*Share) Identity 

func (share *Share) Identity() ResourceRef

Identity returns a ResourceRef identifying this share resource.

func (*Share) Intent 

func (share *Share) Intent() Intent

Intent controls if a resource is to be created/updated or removed.

func (*Share) MarshalJSON 

func (share *Share) MarshalJSON() ([]byte, error)

MarshalJSON supports marshalling a Share resource to JSON.

func (*Share) SetCephFS 

func (share *Share) SetCephFS(
	volume, subvolumegroup, subvolume, path string) *Share

SetCephFS modifies a Share resource's CephFS storage parameters.

func (*Share) Type 

func (*Share) Type() ResourceType

Type returns a ResourceType value.

func (*Share) Validate 

func (share *Share) Validate() error

Validate returns an error describing an issue with the resource or nil if the resource object is valid.

type ShareAccess 

type ShareAccess struct {
	Name     string         `json:"name"`
	Category AccessCategory `json:"category"`
	Access   AccessMode     `json:"access"`
}

ShareAccess defines parameters that control the ability to log in to a share with particular access levels.

func (*ShareAccess) Validate 

func (sa *ShareAccess) Validate() error

Validate returns an error describing an issue with the share access object or nil if the object is valid.

type ShowOptions 

type ShowOptions struct {
	// PasswordFilter can be used to filter/obfuscate password values
	// stored on the Ceph cluster.
	PasswordFilter PasswordFilter
}

ShowOptions controls optional behavior of the Show function.

type SourceType 

type SourceType string

SourceType indicates how a Cluster resource refers to another resource it needs. Currently only ResourceSource is available.

type UserGroupSource 

type UserGroupSource struct {
	SourceType SourceType `json:"source_type"`
	Ref        string     `json:"ref"`
}

UserGroupSource identifies a Users and Groups resource that will be used as a source of user and group information on the SMB cluster.

type UserInfo 

type UserInfo struct {
	Name     string `json:"name"`
	Password string `json:"password"`
}

UserInfo defines a user account managed by an SMB server instance.

type UsersAndGroups 

type UsersAndGroups struct {
	IntentValue     Intent                `json:"intent"`
	UsersGroupsID   string                `json:"users_groups_id"`
	Values          *UsersAndGroupsValues `json:"values,omitempty"`
	LinkedToCluster string                `json:"linked_to_cluster,omitempty"`
}

UsersAndGroups is a resource containing user and group definitions that are managed by an SMB server instances that do not use active directory domains.

func NewLinkedUsersAndGroups 

func NewLinkedUsersAndGroups(cluster *Cluster) *UsersAndGroups

NewLinkedUsersAndGroups returns a new UsersAndGroups resource object with default values that link the resource to a particular cluster. Linked resources can only be used by the cluster they link to and are automatically deleted when the linked cluster is deleted.

func NewUsersAndGroups 

func NewUsersAndGroups(ugID string) *UsersAndGroups

NewUsersAndGroups returns a new UsersAndGroups resource object with default values.

func NewUsersAndGroupsToRemove 

func NewUsersAndGroupsToRemove(ugID string) *UsersAndGroups

NewUsersAndGroupsToRemove returns a new UsersAndGroups resource object with default values set to remove the users and groups resource from management.

func (*UsersAndGroups) Identity 

func (ug *UsersAndGroups) Identity() ResourceRef

Identity returns a ResourceRef identifying this users and groups resource.

func (*UsersAndGroups) Intent 

func (ug *UsersAndGroups) Intent() Intent

Intent controls if a resource is to be created/updated or removed.

func (*UsersAndGroups) MarshalJSON 

func (ug *UsersAndGroups) MarshalJSON() ([]byte, error)

MarshalJSON supports marshalling a UsersAndGroups resource to JSON.

func (*UsersAndGroups) SetValues 

func (ug *UsersAndGroups) SetValues(
	users []UserInfo, groups []GroupInfo) *UsersAndGroups

SetValues modifies a UsersAndGroups resource's users list and groups list.

func (*UsersAndGroups) Type 

func (*UsersAndGroups) Type() ResourceType

Type returns a ResourceType value.

func (*UsersAndGroups) Validate 

func (ug *UsersAndGroups) Validate() error

Validate returns an error describing an issue with the resource or nil if the resource object is valid.

type UsersAndGroupsValues 

type UsersAndGroupsValues struct {
	Users  []UserInfo  `json:"users,omitempty"`
	Groups []GroupInfo `json:"groups,omitempty"`
}

UsersAndGroupsValues contains user and group definitions managed by an SMB server instance.

Source Files

View all Source files

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.