yunfeiguan / acltool Goto Github PK

ACLTOOL

  This is a tool to manage NFSv4/ZFS (also known as Extended on MacOS) ACLs.
  That is listing, creating, editing, searching, stripping, sorting and
  removing redundant entries and more.

  It currently does not support old POSIX.1e or other kinds of ACLs and due to
  missing support on Linux only works over NFSv4.
  
  Bits and pieces of command names (lac/edac/sac) and how abbreviations
  of command names and command name switches work is inspired by the now
  long defunct Prime/PRIMOS operating system.

  There is also some limited support for managing extended attributes which
  might be a useful tool to access low-level ACLs on some systems.



AUTHOR

  Peter Eriksson <[email protected]>



PRIMARY DOWNLOAD SITE

  https://github.com/ptrrkssn/acltool
  


OPERATING SYSTEMS SUPPORTED

  - FreeBSD (ZFS & NFSv4, tested on 11.3 & 12.1)
  - Solaris (ZFS & NFSv4, tested on OmniOS)
  - Linux (NFSv4 only, tested on Ubuntu 18 & 20, CentOS 7 & Debian 9)
  - MacOS (HFS+ & NFSv4, tested with MacOS 10.15)

All the above also support extended attributes more or less.



FILESYSTEMS SUPPORT

  - NFSv4
  - ZFS (but not on Linux sadly - lacks kernel support)
  - HFS+ (MacOS)
  - SMB - if built with Samba (libsmbclient)



OPTIONAL DEPENDENCIES

  Ubuntu/Debian (apt install):
    libreadline-dev
    libsmbclient-dev

  CentOS (yum install)
    readline-devel
    libsmbclient-devel
    
  FreeBSD (pkg install)
    readline
    samba

  Illumos (pkg install)
    readline
    (you'll have to build Samba yourself)



BUILD INSTRUCTIONS

  1. Install the optional dependencies mentioned above
  
  2. If you want to build with SMB support via Samba you may want to
     apply the patch in 'patches' for Samba first. Atleast if you care
     about the order of entries in ACLs that are written.

  3. Run "./configure" (optionally with arguments).

     The configure script will try to autodetect the optional
     dependencies by looking in the standard locations and via
     "pkg-config" if that fails. You may also force it to look
     in nonstandard locations via:

       --with-readline=/path/to/readline
       --with-libsmbclient=/path/to/samba

     The path's should point to directories containing "lib" and
     "include" subdirectories.
     
     Then type 'make' in the source directory and it will automatically
     build the tool.

  4. Run "make install" to install

  5. Some partial support for creating "packages" for operating systems
     can be found in the "pkgs" directory. See the README files in the
     specific subdirectories for details.


USAGE

  See the manual page for detailed usage information.

  Acltool can either be used directly from the command line or by
  entering a CLI mode by starting it without any arguments (sans
  any global options).

  You can access environmental variables using ${NAME} (or $N if
  one-character names).
  
  All commands and long option names can be abbreviated using the
  parts of the names. Some examples of valid abbreviations:

    list-access, lac,  list-a, l-ac, liac
    edit-access, edac, edit-a, e-ac,
    set-access,  sac,  set-a, seta

  Tab-completion in CLI mode also works for command names,
  (global) long options and files.
  
  Command names may also be used in links to the "acltool"
  binary like "ln -s acltool lac" and then be used as shortcuts
  to the commands.

  There is a limited support in CLI mode for navigating a virtual
  filesystem space, including over SMB (if built with Samba) using
  commands like "cd", "dir" etc.



MISCELLANEOUS INFORMATION

FILE TYPES
  f = Regular file
  d = Directory
  b = Block device
  c = Character device
  l = Symbolic link
  p = Pipe (FIFO)
  s = Socket
  w = Whiteout (FreeBSD only)


ACL PRINT STYLES
  default         acltool-style
  standard        FreeBSD-style
  verbose	  More verbose version
  brief		  One-line version
  csv		  CSV-style one-line version
  solaris	  Solaris-style
  primos	  Prime/PRIMOS-style
  samba		  Samba-style
  icacls	  Windows ICACLS-style



MORE INFORMATION

  See the information in the "doc" subdirectory.



SOME KNOWN PROBLEMS

Samba forces it's own ACL sorting rules when setting them via "smb://"-path:s
so our sorting order is ignored/overridden.

Linux currently only allows updating of ACLs over NFSv4. _Not_directly on ZFS.

MacOS has known problems with NFSv4 & Kerberos - kernel-crashing problems. So
while it works for a short while (if you're brave enough) expect your machine to
crash and restart without warning (for example if your Kerberos ticket expires,
or when your machine returns from sleep).



EXAMPLES

  cd smb://user@server/share
    Access a SMB share
    
  dir -v
    List the content of the current directory (verbosely)
  
  list-access -r -t sf .
    Recursively display Access list for sockets and normal files

  lac ${HOME}/some-dir
    List the ACL for ~/some-dir
    
  set-access -r peter86:rwx:f:allow dir
    Recursively set permissions "rwx" (and "f" flags to directories).
    
  touch-access -sm dir
    Sort and merge the ACL entries for dir

  rename-access -r employees=students,g:guests=owner@ /export/homes
    Recursively replace all ACL entries for users/groups "students" with users/groups "employees"
    and "owner@" with "group:guests".

  edit-access -r user:peter86:rwx:f:allow dir
    Recursively set the ACE permission "rwx" on all objects matching "user:peter86"
    with flags "f" and type "allow".

  edit-access -r peter86:-rwx:f:allow dir
    Recursively remove permissions "rwx" from all existing peter86:*:f:allow ACEs

  edit-access -r peter86:+rwx:f:allow dir
    Recursively add permissions "rwx" to all existing peter86:*:f:allow ACEs set on directories

  edit-access -e '0-3/peter86:.*/s mikha02:rwx' path
    Scan ACE entries 0-3 for entries matching "peter86:.*" and replace them with "mikha02:rwx::allow"
 
  edit-access /parst38:rwx/user:peter86:rwx:f:allow/ dir  
    Replace all parst38-allow entries where rwx permissions is
    set with 'user:peter86:rwx:f:allow'

  list-attribute some-file
    List all extended attributes (if any) for file "some-file"
    

MORE ADVANCED USAGE

The "edit-access" subcommand takes two additional command line switches:

  -e <change-list>       Add a semicolon-separated "extended program" to the change request list
  -E <filename>		 Add a "extended program" (semicolon or newline-separated) from a file

If either is specified then no "simple" change-request is read from the command line.

The "extended program" is (very) loosely based on "sed" and consists of a semicolon
(or newlines when reading from a file) separated list of actions having a format like this:

  [{<filetypes>}] [<range>] [/<filter>/] <cmd>[<modifiers>] [<arguments>]

Filetypes are used to select which file types to operate on.

Ranges are used to limit which entries of an ACL to operate on.

Filters are used to further select which ACL entries to operate on.

Modifiers are used to modify the functionality of a command.

For example:

  {fd}0-3/peter86/p;0i peter86:rwx
  
The following commands are available:

  p         Print entries
  d         Delete entries
  i <ace>   Insert entries
  a <ace>   Append entries (after current position)
  s <ace>   Set entries


EXAMPLES

  edit-access -e '2d' dir
    Delete entry #2

  edit-access -e '2i user:peter86:rwx:f:allow' dir
    Insert "user:peter86:rwx:f:allow" at position 2

  edit-access -e '$a user:peter86:rwx:f:allow' dir
    Add entry "user:peter86:rwx:f:allow" last in the ACL

  edit-access -e '0p;1,2,3p;0-$p' dir
    Print first entry, then entries 1,2&3, and then all entries in the ACL

  edit-access -r -e '{d}/peter86:+rwx/s peter86:rwxp:fd;0-$p' dir
    Recursively replace all "peter86:*::allow" entries where atleast rwx is set
    with "peter86:rwxp:fd" on directories, and then print the resulting ACL.