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-privileged 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 Please also note that macOS systems have been reported to have their /usr and/or /usr/local
  86 directories set to be writable to regular user accounts when homebrew is installed. If this is the case, fix this before
  87 installing doas. Having these directories, like /usr/local/bin and /usr/local/etc, writable
  88 to your user means anyone can remove and replace your doas.conf file or the doas binary,
  89 allowing anyone or any program to run commands as root on your system or harvest your password.
  90 This is a large security hole and outside the scope of doas.
  91
  92
  93 #### illumos
  94
  95      PREFIX=/opt/local gmake install
  96
  97
  98 ## Creating a configuration file
  99
 100 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
 101
 102       permit <user> as root
 103
 104 Where <user> is the username of the person who is being granted root access. For instance:
 105
 106       permit jesse as root
 107
 108 Additional users can be added to the file, one per line.
 109
 110 Please note that a shell script, vidoas, is included with the doas program. The vidoas
 111 script must be run as the root user and will perform a syntax check on the doas.conf
 112 file before installing it on the system. This avoids breaking the doas.conf file. The
 113 vidoas script accepts no parameters and can be simply run as
 114
 115       vidoas
 116
 117
 118 To make use of doas, run it in front of any command. Here are some examples:
 119
 120 Confirm doas is working by printing our effective user ID:
 121
 122      doas id
 123
 124 Create a new file in the root user's home:
 125
 126      doas touch /root/new-file
 127
 128 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:
 129
 130      doas -- rm -rf old-directory
 131
 132 ## Contributing
 133
 134 Contributions, in various forms, are always welcome. If you run into a problem or have an improvement you would like to see included, pelase use GitHub's tools to submit an issue ticket or a pull request. Should you encounter a bug  you feel is a security concern, please contact the developer privately at jessefrgsmith AT yahoo DOT ca.
 135
 136 Financial donations are always welcome and can be submitted via PayPal to jessefrgsmith AT yahoo DOT ca or through Patreon at https://www.patreon.com/sysvinit . Thank you for your support.