jailfs

package
v1.0.73 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package jailfs provides a jailed filesystem backend built on Linux openat2.

This file implements the "no symlinks anywhere" filesystem policy by performing every per-request filesystem operation through file descriptors rooted at the jail. Every client path lookup uses openat2 with RESOLVE_IN_ROOT|RESOLVE_NO_SYMLINKS so that:

  • The supplied directory fd is treated as the filesystem root.
  • No symlink is followed during path resolution; if any component is a symlink the call fails with -ELOOP.
  • ".." cannot escape the jail.

Operations that traditionally take a path (chmod, chown, truncate, mkdir, unlink, rename) are implemented as openat2 + f*at syscalls so the kernel — not a string pre-check — enforces containment, eliminating the TOCTOU window between the pre-check and the action.

Setting access/modification times (SFTP Acmodtime) is performed through an openat2-obtained fd, so timestamp updates follow the same containment policy.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckSupport

func CheckSupport() error

CheckSupport checks whether openat2 is available so callers can fail at startup rather than at the first filesystem request. Temporary probe errors are returned to the caller and can be retried by calling CheckSupport again.

func CleanPath

func CleanPath(p string) string

CleanPath normalises a client-supplied path into a slash-separated, jail-relative path suitable for openat2(rootFd, ...). The result never starts with "/" and never contains "." or ".." segments after cleaning. The jail root itself is represented as ".".

Types

type Dir added in v1.0.57

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

Dir is a directory cursor pinned to the directory opened by OpenDir. Reads, rewinds, and Close are safe to call concurrently. They serialize access to the cursor and its descriptor, including entry metadata lookups. A Dir must not be copied after first use.

func (*Dir) Close added in v1.0.57

func (d *Dir) Close() error

Close releases the directory descriptor. Repeated calls return nil.

func (*Dir) ReadInto added in v1.0.57

func (d *Dir) ReadInto(entries []os.FileInfo) (int, error)

ReadInto fills entries with successive directory entries, reading names in batches of at most 512. Metadata is read relative to the open directory without following symlinks; entries whose metadata cannot be read are skipped, matching ListStream. Directory changes are not snapshotted.

It returns io.EOF when it reaches the end, possibly with entries. An empty buffer does not advance the cursor. Reads after Close return os.ErrClosed.

func (*Dir) Rewind added in v1.0.57

func (d *Dir) Rewind() error

Rewind restarts iteration at the beginning of the same open directory. It does not resolve the original path again. Rewinding a closed cursor returns os.ErrClosed.

type FS

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

FS encapsulates a fd-relative, no-symlink filesystem rooted at a single directory. Every method validates the path through the kernel using openat2; no string-level resolution or pre-check is performed.

Filesystem operations are safe for concurrent use. The root descriptor is fixed at construction; Close must run only after those operations finish.

func Open

func Open(root string) (*FS, error)

Open opens a configured jail root without following symlinks in any path component. Blank roots and literal ".." components are rejected before path normalization. Relative roots use a cwd descriptor held until the jail-root descriptor has been opened.

The returned FS keeps that directory open for its lifetime, so renaming or replacing the configured path cannot redirect subsequent filesystem access. openat2 support (Linux 5.6+) is checked before opening the root.

func (*FS) Chmod

func (j *FS) Chmod(clientPath string, perm os.FileMode) error

Chmod changes the permission bits of a regular file or directory. The inode is pinned and type-checked before opening it for fchmod. Symlinks anywhere in the client path cause failure.

func (*FS) Chown

func (j *FS) Chown(clientPath string, uid, gid int) error

Chown changes the owner/group of clientPath. The lookup goes through the jail root with RESOLVE_NO_SYMLINKS, then fchownat with AT_EMPTY_PATH on a fd opened with O_PATH operates atomically on the target.

func (*FS) Chtimes

func (j *FS) Chtimes(clientPath string, atime, mtime time.Time) error

Chtimes changes the access and modification timestamps of clientPath. The lookup goes through openat2 with RESOLVE_NO_SYMLINKS, then utimensat with AT_EMPTY_PATH applies the timestamps to that fd without reopening by path.

func (*FS) Close

func (j *FS) Close() error

Close releases the jail root fd after all filesystem operations finish. After Close, further calls return EBADF.

func (*FS) FullPath

func (j *FS) FullPath(clientPath string) string

FullPath returns the reporting path for a client-supplied path. The input is cleaned and confined to the jail-relative form before joining it to the configured root. Filesystem operations use the retained root descriptor; this reporting path may become stale if the root or an ancestor is renamed.

func (*FS) List

func (j *FS) List(clientPath string) ([]os.FileInfo, error)

List opens the directory at clientPath and returns its entries as []os.FileInfo. The directory itself must not be a symlink (enforced by openat2). Individual entries are returned as the kernel reports them; per policy, symlinks among the entries can never be followed by subsequent operations, so listing them is harmless.

Entries are stat'd via fstatat against the directory fd so the per-entry metadata lookup also goes through the openat2-rooted directory and never follows a symlink.

func (*FS) ListStream

func (j *FS) ListStream(clientPath string, yield func(os.FileInfo) error) error

ListStream invokes yield once per directory entry, pulling dirents in fixed-size batches so a directory with millions of entries does not have to be materialised in memory before being transmitted. Entries that vanish between readdir and fstatat (race with a concurrent unlink) are silently skipped — same tolerance as List. yield may return a non-nil error to terminate the walk early; that error is propagated to the caller unchanged.

func (*FS) Mkdir

func (j *FS) Mkdir(clientPath string, perm os.FileMode) error

Mkdir creates a new directory at clientPath with the given permission. The parent directory must already exist and must not be reached through a symlink. The new directory is created with mkdirat against an openat2 fd of the parent, so a TOCTOU race between path check and mkdir is impossible.

func (*FS) MkdirAll

func (j *FS) MkdirAll(clientPath string, perm os.FileMode) error

MkdirAll creates clientPath together with any missing parent directories, like os.MkdirAll, but confined to the jail: every level is created with Mkdir, which resolves the parent through openat2 with RESOLVE_NO_SYMLINKS, so no component may be reached through a symlink and the path cannot escape the jail. Directories that already exist are left untouched; it is an error if a component along the path exists as a non-directory. Passing the jail root (".", "" or "/") is a no-op.

func (*FS) OpenDir added in v1.0.57

func (j *FS) OpenDir(clientPath string) (*Dir, error)

OpenDir opens a directory without following symlinks in any component. It validates the path immediately but reads no entries. The returned cursor keeps referring to the same directory if its path is renamed or replaced, and remains usable after the FS is closed.

func (*FS) OpenRead

func (j *FS) OpenRead(clientPath string) (*os.File, error)

OpenRead opens a regular file for reading. Symlinks anywhere in the path (including the final component) cause the call to fail with EACCES/ELOOP.

func (*FS) OpenWrite

func (j *FS) OpenWrite(clientPath string, flags int, perm os.FileMode) (*os.File, error)

OpenWrite opens a regular file for writing using the given flags and mode. Callers pass the standard os.O_* flags (typically O_CREATE|O_WRONLY|O_TRUNC for uploads, or O_APPEND for FTP APPE). Client paths are resolved through openat2 with no symlinks. Existing inodes are pinned and type-checked before opening for I/O, and truncation follows successful reopening.

func (*FS) Remove

func (j *FS) Remove(clientPath string) error

Remove removes a non-directory entry. Because the parent is reached through an openat2 with RESOLVE_NO_SYMLINKS, no symlink traversal is possible. The final component is not followed by unlinkat, so a symlink at that position is removed as a symlink (not its target) — consistent with os.Remove.

func (*FS) Rename

func (j *FS) Rename(oldPath, newPath string) error

Rename renames oldPath to newPath. Both paths are resolved through openat2 with RESOLVE_NO_SYMLINKS, so neither side may traverse a symlink. The rename itself uses renameat2 with flags=0, preserving the os.Rename semantics of overwriting an existing destination.

func (*FS) Rmdir

func (j *FS) Rmdir(clientPath string) error

Rmdir removes an empty directory.

func (*FS) SetModTime

func (j *FS) SetModTime(clientPath string, mtime time.Time) error

SetModTime changes only the modification timestamp of clientPath. The access timestamp is left unchanged by passing UTIME_OMIT to utimensat.

func (*FS) Stat

func (j *FS) Stat(clientPath string) (os.FileInfo, error)

Stat returns os.FileInfo for the given client path. Because openat2 with RESOLVE_NO_SYMLINKS rejects symlink components, the result is always the stat of a non-symlink. (Lstat is redundant under this policy and is mapped to the same call.)

func (*FS) Truncate

func (j *FS) Truncate(clientPath string, size int64) error

Truncate sets the size of a regular file after pinning and validating its inode. The initial lookup uses openat2 so symlink traversal is impossible.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址