acls

package module
v0.1.5 Latest Latest
Warning

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

Go to latest
Published: Jan 19, 2026 License: BSD-3-Clause Imports: 10 Imported by: 2

README

codecov

Overview

This library provides a pure Go implementation for managing Linux filesystem Access Control Lists (ACLs) without any cgo dependencies. It allows you to programmatically adjust both regular access ACLs (system.posix_acl_access) and default ACLs (system.posix_acl_default), serving as a native Go alternative to the getfacl and setfacl command-line tools.

Key Features:

  • 🔒 No cgo dependencies - Pure Go implementation for maximum portability
  • 🛡️ Immutable entries - ACL entries are immutable; modifications create new entries
  • 🎯 Type-safe - Strong typing for tags, permissions, and IDs
  • 🧰 Intuitive API - Fluent interface for permission manipulation
  • ✅ Well-tested - Comprehensive test coverage

Sample

Basic Usage

This example demonstrates loading ACL entries from a file, adding a new entry, and applying the modified ACL back to the filesystem.

package main

import (
    "fmt"
    log "github.com/sirupsen/logrus"
    "github.com/steiler/acls"
)

func main() {
    // Define the path to the file for which you want to manage ACLs
    filePath := "/tmp/foo"

    // Create a new ACL instance
    a := acls.NewACL()
    
    // Load existing ACL entries from the filesystem
    // If no ACL is attached, this loads standard POSIX permissions as ACL entries
    err := a.Load(filePath, acls.PosixACLAccess)
    if err != nil {
        log.Fatal(err)
    }
    
    // Add a new entry: grant group 5558 read+write+execute permissions
    err = a.AddEntry(acls.NewEntry(acls.TAG_ACL_GROUP, 5558, acls.PermAll))
    if err != nil {
        log.Fatal(err)
    }
    
    // Print a human-readable representation of the ACL
    fmt.Println(a.String())

    // Apply the modified ACL back to the filesystem as an access ACL
    err = a.Apply(filePath, acls.PosixACLAccess)
    if err != nil {
        log.Fatal(err)
    }
}

The output of the fmt.Println(a.String()) looks like the following:

Version: 2
Entries:
Tag:   USER_OBJ ( 1), ID:       1000, Perm: rwx (7)
Tag:  GROUP_OBJ ( 4), ID:       1000, Perm: rwx (7)
Tag:      GROUP ( 8), ID:       5558, Perm: rwx (7)
Tag:       MASK (16), ID: 4294967295, Perm: rwx (7)
Tag:      OTHER (32), ID: 4294967295, Perm: r-x (5)

Iterating Over Entries

You can retrieve and iterate over all ACL entries:

a := acls.NewACL()
a.Load(filePath, acls.PosixACLAccess)

for _, entry := range a.GetEntries() {
    fmt.Printf("Tag: %s, ID: %d, Perm: %s\n", 
        acls.Tag2String(entry.Tag()), 
        entry.ID(), 
        acls.PermUintToString(entry.Perm()))
}

Permission Manipulation

The library provides convenient methods for working with permissions:

a := acls.NewACL()
a.Load(filePath, acls.PosixACLAccess)

// Add execute permission to all entries that have read permission
for _, entry := range a.GetEntries() {
    if entry.HasPerm(acls.PermRead) {
        // Create a new entry with execute permission added
        newEntry := entry.WithPerm(acls.PermExecute)
        a.AddEntry(newEntry)
    }
}

// Create an entry with exact permissions
entry := acls.NewEntry(acls.TAG_ACL_USER, 1000, acls.PermRead|acls.PermWrite)

// Remove write permission
readOnlyEntry := entry.WithoutPerm(acls.PermWrite)

// Set exact permissions
rwxEntry := entry.WithExactPerm(acls.PermAll)

Available permission constants:

  • acls.PermRead - Read permission (r--)
  • acls.PermWrite - Write permission (-w-)
  • acls.PermExecute - Execute permission (--x)
  • acls.PermAll - All permissions (rwx)
  • acls.PermNone - No permissions (---)

Features

  • Add ACL Entry
  • Delete ACL Entry
  • Get specific ACL Entry
  • Get all ACL Entries
  • Modify ACL Entry (via delete + add)
  • Read ACL entry fields (Tag, ID, Permission)
  • Permission manipulation (add, remove, set, check)
  • Permission constants for cleaner code
  • Print ACL Entry
  • Read ACL entries from one file object, apply to another
  • Adjust default and access ACL
  • Convert between string and numeric permission formats

Documentation

Index

Constants

View Source
const (
	// Undefined ACL type.
	TAG_ACL_UNDEFINED_FIELD = 0x0
	// Discretionary access rights for
	//processes whose effective user ID
	//matches the user ID of the file's owner.
	TAG_ACL_USER_OBJ = 0x1
	// Discretionary access rights for
	// processes whose effective user ID
	// matches the ACL entry qualifier.
	TAG_ACL_USER = 0x2
	// Discretionary access rights for
	// processes whose effective groupID or
	// any supplemental groups match the group
	// ID of the file's owner.
	TAG_ACL_GROUP_OBJ = 0x4
	// Discretionary access rights for
	// processes whose effective group ID or
	// any supplemental groups match the ACL
	// entry qualifier.
	TAG_ACL_GROUP = 0x8
	// The maximum discretionary access rights
	// that can be granted to a process in the
	// file group class. This is only valid
	// for POSIX.1e ACLs.
	TAG_ACL_MASK = 0x10
	// Discretionary access rights for
	// processes not covered by any other ACL
	// entry. This is only valid for POSIX.1e
	// ACLs.
	TAG_ACL_OTHER = 0x20
	// Same as ACL_OTHER.
	TAG_ACL_OTHER_OBJ = TAG_ACL_OTHER
	// Discretionary access rights for all
	// users. This is only valid for NFSv4
	// ACLs.
	TAG_ACL_EVERYONE = 0x40
)
View Source
const (
	PermRead    uint16 = 0x4
	PermWrite   uint16 = 0x2
	PermExecute uint16 = 0x1
	PermAll     uint16 = 0x7
	PermNone    uint16 = 0x0
)

Permission bit constants

Variables

This section is empty.

Functions

func PermStringToUint added in v0.1.5

func PermStringToUint(s string) (uint16, error)

PermStringToUint takes a string representation of a permission "rwx" and returns the uint16 representation. an error is returned if the string is not exactly 3 characters long.

func PermUintToString

func PermUintToString(p uint16) string

PermUintToString takes an int representation of a permission and returns the string representation "rwx". not granted permissions appear as "-".

func Tag2String

func Tag2String(i Tag) string

Types

type ACL

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

ACL handles Posix ACL data

func NewACL added in v0.1.5

func NewACL() *ACL

NewACL returns a new ACL instance

func (*ACL) AddEntry

func (a *ACL) AddEntry(e *ACLEntry) error

AddEntry adds the given entry to the ACL It will make sure that no entry with the same Tag and ID combination exists. If so, it will replace (not merge) the existing entry with the given.

func (*ACL) Apply

func (a *ACL) Apply(fsPath string, attr ACLAttr) error

Apply applies the ACL with its ACLEntries to as either access or default ACLs to the given filesstem path

func (*ACL) DeleteEntry

func (a *ACL) DeleteEntry(e *ACLEntry) *ACLEntry

DeleteEntry deletes the entry that has the same tag and id if it exists and returns the deleted entry

func (*ACL) EntryExists

func (a *ACL) EntryExists(e *ACLEntry) int

EntryExists checks if an entry with the given Tag and ID already exist if so it return -1 of not the position of the duplicate is returned as a positive int

func (*ACL) Equal

func (a *ACL) Equal(e *ACL) bool

Equal returns true if the given ACL equals the actual ACL

func (*ACL) GetEntries added in v0.1.4

func (a *ACL) GetEntries() []*ACLEntry

GetEntries returns all ACLEntries of the ACL

func (*ACL) GetEntry added in v0.1.3

func (a *ACL) GetEntry(e *ACLEntry) *ACLEntry

GetEntry returns the entry with the given Tag and ID if it exists, nil otherwise

func (*ACL) Load

func (a *ACL) Load(fsPath string, attr ACLAttr) error

Load loads the attr defined POSIX.ACL type (access or default) from the given filepath

func (*ACL) String

func (a *ACL) String() string

String returns a human readable for of the ACL

func (*ACL) ToByteSlice

func (a *ACL) ToByteSlice(result *bytes.Buffer)

ToByteSlice return the ACL in its byte slice representation read to be used by Setxattr(...)

type ACLAttr

type ACLAttr string
const (
	PosixACLAccess  ACLAttr = "system.posix_acl_access"
	PosixACLDefault ACLAttr = "system.posix_acl_default"
)

type ACLEntry

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

ACLEntry the ACLEntry represents the single lines of permission.

  • tag references the type (group, user, etc.)
  • perm is the permission in its numerical format
  • id is the id of the group or user or whatever tag points to

func NewEntry

func NewEntry(tag Tag, id uint32, perm uint16) *ACLEntry

NewEntry returns a new ACLEntry

func (*ACLEntry) Equal

func (a *ACLEntry) Equal(e *ACLEntry) bool

Equal returns true if the given ACLEntry equals the actual ACLEntry

func (*ACLEntry) HasPerm added in v0.1.5

func (e *ACLEntry) HasPerm(perm uint16) bool

HasPerm checks if the entry has the specified permission bit(s)

func (*ACLEntry) ID added in v0.1.5

func (e *ACLEntry) ID() uint32

ID returns the ID of the ACLEntry

func (*ACLEntry) Perm added in v0.1.5

func (e *ACLEntry) Perm() uint16

Perm returns the permission of the ACLEntry

func (*ACLEntry) String

func (a *ACLEntry) String() string

String returns a string representation of the ACLEntry

func (*ACLEntry) Tag added in v0.1.5

func (e *ACLEntry) Tag() Tag

Tag returns the tag of the ACLEntry

func (*ACLEntry) ToByteSlice

func (a *ACLEntry) ToByteSlice(result *bytes.Buffer)

ToByteSlice returns the ACLEntry as a byte slice in little endian order, which is the representation required for the Setxattr(...) call

func (*ACLEntry) WithExactPerm added in v0.1.5

func (e *ACLEntry) WithExactPerm(perm uint16) *ACLEntry

WithExactPerm returns a new ACLEntry with the exact permission specified

func (*ACLEntry) WithPerm added in v0.1.5

func (e *ACLEntry) WithPerm(perm uint16) *ACLEntry

WithPerm returns a new ACLEntry with the specified permission bit(s) added

func (*ACLEntry) WithoutPerm added in v0.1.5

func (e *ACLEntry) WithoutPerm(perm uint16) *ACLEntry

WithoutPerm returns a new ACLEntry with the specified permission bit(s) removed

type Tag

type Tag uint16

Jump to

Keyboard shortcuts

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