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 ¶
- func CheckSupport() error
- func CleanPath(p string) string
- type Dir
- type FS
- func (j *FS) Chmod(clientPath string, perm os.FileMode) error
- func (j *FS) Chown(clientPath string, uid, gid int) error
- func (j *FS) Chtimes(clientPath string, atime, mtime time.Time) error
- func (j *FS) Close() error
- func (j *FS) FullPath(clientPath string) string
- func (j *FS) List(clientPath string) ([]os.FileInfo, error)
- func (j *FS) ListStream(clientPath string, yield func(os.FileInfo) error) error
- func (j *FS) Mkdir(clientPath string, perm os.FileMode) error
- func (j *FS) MkdirAll(clientPath string, perm os.FileMode) error
- func (j *FS) OpenDir(clientPath string) (*Dir, error)
- func (j *FS) OpenRead(clientPath string) (*os.File, error)
- func (j *FS) OpenWrite(clientPath string, flags int, perm os.FileMode) (*os.File, error)
- func (j *FS) Remove(clientPath string) error
- func (j *FS) Rename(oldPath, newPath string) error
- func (j *FS) Rmdir(clientPath string) error
- func (j *FS) SetModTime(clientPath string, mtime time.Time) error
- func (j *FS) Stat(clientPath string) (os.FileInfo, error)
- func (j *FS) Truncate(clientPath string, size int64) error
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.
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
Close releases the directory descriptor. Repeated calls return nil.
func (*Dir) ReadInto ¶ added in v1.0.57
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Close releases the jail root fd after all filesystem operations finish. After Close, further calls return EBADF.
func (*FS) FullPath ¶
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 ¶
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 ¶
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 ¶
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 ¶
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
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 ¶
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 ¶
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 ¶
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 ¶
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) SetModTime ¶
SetModTime changes only the modification timestamp of clientPath. The access timestamp is left unchanged by passing UTIME_OMIT to utimensat.