README.md

   1 # doas
   2 A port of OpenBSD's doas which runs on FreeBSD, Linux, NetBSD, illumos and macOS.
   3
   4 The doas utility is a program originally written for OpenBSD which allows a user to run a command as though they were another user. Typically doas is used to allow non-privleged users to run commands as though they were the root user. The doas program acts as an alternative to sudo, which is a popular method in the Linux community for granting admin access to specific users.
   5
   6 The doas program offers two benefits over sudo: its configuration file has a simple syntax and it is smaller, requiring less effort to audit the code. This makes it harder for both admins and coders to make mistakes that potentially open security holes in the system.
   7
   8 This port of doas has been made to work on FreeBSD 11.x and newer, most distributions of Linux, NetBSD 8.x and newer, and most illumos distributions (tested on OmniOS and SmartOS). It also works on macOS Catalina.
   9
  10 Installing doas is accomplished in three steps:
  11
  12 0. Optionally install the package/port for your operating system, OR
  13 1. Installing build tools.
  14 2. Compiling and installing the doas utility.
  15 3. Creating a configuration file for doas.
  16
  17 ## Installation via packages/repositories:
  18
  19 [For Arch Linux users (and Arch-based distributions) there is a package available in the AUR:](https://aur.archlinux.org/packages/doas/)
  20 ```
  21  ~ git clone https://aur.archlinux.org/doas.git
  22  ~ cd doas
  23  ~ makepkg -si
  24 ```
  25
  26 The doas command is in FreeBSD's ports collection and may be installed by simply running the following command as the root user:
  27
  28       pkg install doas
  29
  30
  31 ## Installing build tools
  32
  33 1 - The doas program has virtually no dependencies. So long as you have a compiler (such as the GNU Compiler or Clang) installed and GNU make (gmake on NetBSD, FreeBSD, and illumos). On illumos, the build-essential package will install all the necessary build tools.
  34
  35 #### Debian and Ubuntu based distributions
  36
  37      sudo apt install build-essential make bison flex libpam0g-dev
  38
  39 #### macOS
  40
  41      xcode-select --install
  42
  43 ## Compiling and installing
  44
  45 2 - To install doas, download the source code and, in the source code's directory, run the command
  46
  47 #### Linux
  48
  49      make
  50
  51 #### FreeBSD, NetBSD and macOS
  52
  53      gmake
  54
  55 #### illumos
  56
  57      PREFIX=/opt/local gmake
  58
  59 Alternatively, bison can be used if yacc is not installed.
  60
  61      YACC="bison -y" PREFIX=/opt/local gmake
  62
  63 This builds the source code. Then, as the root user, run
  64
  65 #### Linux
  66
  67      make install
  68
  69 Note to Linux users: Some Linux distributions, such as CentOS, will block doas from using PAM authentication by default. If this happens, it is usually possible to work around the issue by running the following command as the administrator:
  70
  71       cp /etc/pam.d/sudo /etc/pam.d/doas
  72
  73
  74 #### FreeBSD and NetBSD
  75
  76      gmake install
  77
  78 #### macOS
  79
  80      gmake install
  81      cp /etc/pam.d/sudo /etc/pam.d/doas
  82
  83 Note: By default macOS blocks doas from using PAM modules, causing doas authentication to fail. The cp command above copies the sudo PAM configuration into place for doas to use.
  84
  85
  86 #### illumos
  87
  88      PREFIX=/opt/local gmake install
  89
  90
  91 ## Creating a configuration file
  92
  93 3 - The doas configuration file is located at /usr/local/etc/doas.conf or /opt/local/etc/doas.conf for illumos. To create a rule allowing a user to perform admin actions, add a line to the configuration file. Details on how to do this are covered in the doas.conf manual page. However, most of the time a rule is as simple as
  94
  95       permit <user> as root
  96
  97 Where <user> is the username of the person who is being granted root access. For instance:
  98
  99       permit jesse as root
 100
 101 Additional users can be added to the file, one per line.
 102
 103 Please note that a shell script, vidoas, is included with the doas program. The vidoas
 104 script can be run as a regular user and will perform a syntax check on the doas.conf
 105 file before installing it on the system. This avoids breaking the doas.conf file. The
 106 vidoas script accepts no parameters and can be simply run as
 107
 108       vidoas
 109
 110
 111 To make use of doas, run it in front of any command. Here are some examples:
 112
 113 Confirm doas is working by printing our effective user ID:
 114
 115      doas id
 116
 117 Create a new file in the root user's home:
 118
 119      doas touch /root/new-file
 120
 121 On Linux versions of doas prior to 6.3p1 required commands with arguments to be prefixed by a double-dash (--). From 6.3p1 and onward the double-dash is no longer required. Here we remove a directory owned by root:
 122
 123      doas -- rm -rf old-directory