nfs

package
v1.70.3 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2025 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package nfs implements a server to serve a VFS remote over the NFSv3 protocol

There is no authentication available on this server and it is served on the loopback interface by default.

This is primarily used for mounting a VFS remote in macOS, where FUSE-mounting mechanisms are usually not available.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrorSymlinkCacheNotSupported = errors.New("symlink cache not supported on " + runtime.GOOS)
	ErrorSymlinkCacheNoPermission = errors.New("symlink cache must be run as root or with CAP_DAC_READ_SEARCH")
)

Errors on cache initialisation

View Source 
var Command = &cobra.Command{
	Use:   "nfs remote:path",
	Short: `Serve the remote as an NFS mount`,
	Long: strings.ReplaceAll(`Create an NFS server that serves the given remote over the network.
	
This implements an NFSv3 server to serve any rclone remote via NFS.

The primary purpose for this command is to enable the [mount
command](/commands/rclone_mount/) on recent macOS versions where
installing FUSE is very cumbersome.

This server does not implement any authentication so any client will be
able to access the data. To limit access, you can use |serve nfs| on
the loopback address or rely on secure tunnels (such as SSH) or use
firewalling.

For this reason, by default, a random TCP port is chosen and the
loopback interface is used for the listening address by default;
meaning that it is only available to the local machine. If you want
other machines to access the NFS mount over local network, you need to
specify the listening address and port using the |--addr| flag.

Modifying files through the NFS protocol requires VFS caching. Usually
you will need to specify |--vfs-cache-mode| in order to be able to
write to the mountpoint (|full| is recommended). If you don't specify
VFS cache mode, the mount will be read-only.

|--nfs-cache-type| controls the type of the NFS handle cache. By
default this is |memory| where new handles will be randomly allocated
when needed. These are stored in memory. If the server is restarted
the handle cache will be lost and connected NFS clients will get stale
handle errors.

|--nfs-cache-type disk| uses an on disk NFS handle cache. Rclone
hashes the path of the object and stores it in a file named after the
hash. These hashes are stored on disk the directory controlled by
|--cache-dir| or the exact directory may be specified with
|--nfs-cache-dir|. Using this means that the NFS server can be
restarted at will without affecting the connected clients.

|--nfs-cache-type symlink| is similar to |--nfs-cache-type disk| in
that it uses an on disk cache, but the cache entries are held as
symlinks. Rclone will use the handle of the underlying file as the NFS
handle which improves performance. This sort of cache can't be backed
up and restored as the underlying handles will change. This is Linux
only. It requires running rclone as root or with |CAP_DAC_READ_SEARCH|.
You can run rclone with this extra permission by doing this to the
rclone binary |sudo setcap cap_dac_read_search+ep /path/to/rclone|.

|--nfs-cache-handle-limit| controls the maximum number of cached NFS
handles stored by the caching handler. This should not be set too low
or you may experience errors when trying to access files. The default
is |1000000|, but consider lowering this limit if the server's system
resource usage causes problems. This is only used by the |memory| type
cache.

To serve NFS over the network use following command:

    rclone serve nfs remote: --addr 0.0.0.0:$PORT --vfs-cache-mode=full

This specifies a port that can be used in the mount command. To mount
the server under Linux/macOS, use the following command:
    
    mount -t nfs -o port=$PORT,mountport=$PORT,tcp $HOSTNAME:/ path/to/mountpoint

Where |$PORT| is the same port number used in the |serve nfs| command
and |$HOSTNAME| is the network address of the machine that |serve nfs|
was run on.

This command is only available on Unix platforms.

`, "|", "`") + vfs.Help(),
	Annotations: map[string]string{
		"versionIntroduced": "v1.65",
		"groups":            "Filter",
		"status":            "Experimental",
	},
	Run: Run,
}

Command is the definition of the command

View Source 
var OnUnmountFunc func()

OnUnmountFunc registers a function to call when externally unmounted

View Source 
var OptionsInfo = fs.Options{{
	Name:    "addr",
	Default: "",
	Help:    "IPaddress:Port or :Port to bind server to",
}, {
	Name:    "nfs_cache_handle_limit",
	Default: 1000000,
	Help:    "max file handles cached simultaneously (min 5)",
}, {
	Name:    "nfs_cache_type",
	Default: cacheMemory,
	Help:    "Type of NFS handle cache to use",
}, {
	Name:    "nfs_cache_dir",
	Default: "",
	Help:    "The directory the NFS handle cache will use if set",
}}

OptionsInfo descripts the Options in use

Functions

func AddFlags 

func AddFlags(flagSet *pflag.FlagSet)

AddFlags adds flags for serve nfs (and nfsmount)

func NewHandler added in v1.70.1 

func NewHandler(ctx context.Context, vfs *vfs.VFS, opt *Options) (handler nfs.Handler, err error)

NewHandler creates a handler for the provided filesystem

func Run 

func Run(command *cobra.Command, args []string)

Run the command

Types

type Cache added in v1.70.1 

type Cache interface {
	// ToHandle takes a file and represents it with an opaque handle to reference it.
	// In stateless nfs (when it's serving a unix fs) this can be the device + inode
	// but we can generalize with a stateful local cache of handed out IDs.
	ToHandle(f billy.Filesystem, path []string) []byte

	// FromHandle converts from an opaque handle to the file it represents
	FromHandle(fh []byte) (billy.Filesystem, []string, error)

	// Invalidate the handle passed - used on rename and delete
	InvalidateHandle(fs billy.Filesystem, handle []byte) error

	// HandleLimit exports how many file handles can be safely stored by this cache.
	HandleLimit() int
}

Cache controls the file handle cache implementation

type FS 

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

FS is our wrapper around the VFS to properly support billy.Filesystem interface

func (*FS) Capabilities 

func (f *FS) Capabilities() (caps billy.Capability)

Capabilities exports the filesystem capabilities

func (*FS) Chmod 

func (f *FS) Chmod(name string, mode os.FileMode) (err error)

Chmod changes the file modes

func (*FS) Chown 

func (f *FS) Chown(name string, uid, gid int) (err error)

Chown changes owner of the file

func (*FS) Chroot 

func (f *FS) Chroot(path string) (FS billy.Filesystem, err error)

Chroot is not supported in VFS

func (*FS) Chtimes 

func (f *FS) Chtimes(name string, atime time.Time, mtime time.Time) (err error)

Chtimes changes the access time and modified time

func (*FS) Create 

func (f *FS) Create(filename string) (node billy.File, err error)

Create implements creating new files

func (*FS) Join 

func (f *FS) Join(elem ...string) string

Join joins path elements

func (*FS) Lchown 

func (f *FS) Lchown(name string, uid, gid int) (err error)

Lchown changes the owner of symlink

func (*FS) Lstat 

func (f *FS) Lstat(filename string) (fi os.FileInfo, err error)

Lstat gets the stats for symlink

func (*FS) MkdirAll 

func (f *FS) MkdirAll(filename string, perm os.FileMode) (err error)

MkdirAll creates a directory and all the ones above it it does not redirect to VFS.MkDirAll because that one doesn't honor the permissions

func (*FS) Open 

func (f *FS) Open(filename string) (node billy.File, err error)

Open opens a file

func (*FS) OpenFile 

func (f *FS) OpenFile(filename string, flag int, perm os.FileMode) (node billy.File, err error)

OpenFile opens a file

func (*FS) ReadDir 

func (f *FS) ReadDir(path string) (dir []os.FileInfo, err error)

ReadDir implements read dir 

func (f *FS) Readlink(link string) (result string, err error)

Readlink reads the contents of link

func (*FS) Remove 

func (f *FS) Remove(filename string) (err error)

Remove deletes a file

func (*FS) Rename 

func (f *FS) Rename(oldpath, newpath string) (err error)

Rename renames a file

func (*FS) Root 

func (f *FS) Root() (root string)

Root returns the root of a VFS

func (*FS) Stat 

func (f *FS) Stat(filename string) (fi os.FileInfo, err error)

Stat gets the file stat 

func (f *FS) Symlink(target, link string) (err error)

Symlink creates a link pointing to target

func (*FS) TempFile 

func (f *FS) TempFile(dir, prefix string) (node billy.File, err error)

TempFile is not implemented

type Handler added in v1.70.1 

type Handler struct {
	Cache
	// contains filtered or unexported fields
}

Handler returns a NFS backing that exposes a given file system in response to all mount requests.

func (*Handler) Change added in v1.70.1 

func (h *Handler) Change(fs billy.Filesystem) billy.Change

Change provides an interface for updating file attributes.

func (*Handler) FSStat added in v1.70.1 

func (h *Handler) FSStat(ctx context.Context, f billy.Filesystem, s *nfs.FSStat) error

FSStat provides information about a filesystem.

func (*Handler) FromHandle added in v1.70.1 

func (h *Handler) FromHandle(b []byte) (f billy.Filesystem, s []string, err error)

FromHandle converts from an opaque handle to the file it represents

func (*Handler) HandleLimit added in v1.70.1 

func (h *Handler) HandleLimit() int

HandleLimit exports how many file handles can be safely stored by this cache.

func (*Handler) InvalidateHandle added in v1.70.1 

func (h *Handler) InvalidateHandle(f billy.Filesystem, b []byte) (err error)

InvalidateHandle invalidates the handle passed - used on rename and delete

func (*Handler) Mount added in v1.70.1 

func (h *Handler) Mount(ctx context.Context, conn net.Conn, req nfs.MountRequest) (status nfs.MountStatus, hndl billy.Filesystem, auths []nfs.AuthFlavor)

Mount backs Mount RPC Requests, allowing for access control policies.

func (*Handler) ToHandle added in v1.70.1 

func (h *Handler) ToHandle(f billy.Filesystem, s []string) (b []byte)

ToHandle takes a file and represents it with an opaque handle to reference it. In stateless nfs (when it's serving a unix fs) this can be the device + inode but we can generalize with a stateful local cache of handed out IDs.

type Options 

type Options struct {
	ListenAddr     string      `config:"addr"`                   // Port to listen on
	HandleLimit    int         `config:"nfs_cache_handle_limit"` // max file handles cached by go-nfs CachingHandler
	HandleCache    handleCache `config:"nfs_cache_type"`         // what kind of handle cache to use
	HandleCacheDir string      `config:"nfs_cache_dir"`          // where the handle cache should be stored
}

Options contains options for the NFS Server 

var Opt Options

Opt is the default set of serve nfs options

func (*Options) Limit added in v1.67.2 

func (o *Options) Limit() int

Limit overrides the --nfs-cache-handle-limit value if out-of-range

type Server 

type Server struct {
	UnmountedExternally bool
	// contains filtered or unexported fields
}

Server contains everything to run the Server

func NewServer 

func NewServer(ctx context.Context, vfs *vfs.VFS, opt *Options) (s *Server, err error)

NewServer creates a new server

func (*Server) Addr 

func (s *Server) Addr() net.Addr

Addr returns the listening address of the server

func (*Server) Serve 

func (s *Server) Serve() (err error)

Serve starts the server

func (*Server) Shutdown 

func (s *Server) Shutdown() error

Shutdown stops the server

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.