1# doas
2A port of OpenBSD's doas which runs on FreeBSD, Linux, NetBSD, illumos and macOS.
3
4The 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
6The 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
8This 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
10Installing doas is accomplished in three steps:
11
120. Optionally install the package/port for your operating system, OR
131. Installing build tools.
142. Compiling and installing the doas utility.
153. 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
26The 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
331 - 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#### Fedora
40
41      sudo dnf install gcc gcc-c++ make flex bison pam-devel byacc
42
43#### CentOS 8 and Stream
44
45      sudo dnf install gcc gcc-c++ make flex bison pam-devel byacc git
46
47#### CentOS 7.x
48
49      sudo yum install gcc gcc-c++ make flex bison pam-devel byacc git
50
51#### openSUSE and SUSE Linux Enterprise
52
53      sudo zypper install gcc gcc-c++ make flex bison pam-devel byacc git
54
55#### macOS
56
57     xcode-select --install
58
59## Compiling and installing
60
612 - To install doas, download the source code and, in the source code's directory, run the command
62
63#### Linux
64
65     make
66
67#### FreeBSD, NetBSD and macOS
68
69     gmake
70
71#### illumos
72
73     PREFIX=/opt/local gmake
74
75Alternatively, bison can be used if yacc is not installed.
76
77     YACC="bison -y" PREFIX=/opt/local gmake
78
79This builds the source code. Then, as the root user, run
80
81#### Linux
82
83     make install
84
85Note 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:
86
87      cp /etc/pam.d/sudo /etc/pam.d/doas
88
89In situations where you do not have a /etc/pam.d/sudo file (perhaps due to sudo not being installed)
90then create a new file with your preferred text editor called /etc/pam.d/doas and insert the
91following lines:
92
93      #%PAM-1.0
94      @include common-auth
95      @include common-account
96      @include common-session-noninteractive
97
98After you save this file you may need to reboot in order for the change to take effect.
99
100
101#### FreeBSD and NetBSD
102
103     gmake install
104
105#### macOS
106
107     gmake install
108     cp /etc/pam.d/sudo /etc/pam.d/doas
109
110Note: 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.
111
112Please also note that macOS systems have been reported to have their /usr and/or /usr/local
113directories set to be writable to regular user accounts when homebrew is installed. If this is the case, fix this before
114installing doas. Having these directories, like /usr/local/bin and /usr/local/etc, writable
115to your user means anyone can remove and replace your doas.conf file or the doas binary,
116allowing anyone or any program to run commands as root on your system or harvest your password.
117This is a large security hole and outside the scope of doas.
118
119
120#### illumos
121
122     PREFIX=/opt/local gmake install
123
124
125## Creating a configuration file
126
1273 - 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
128
129      permit <user> as root
130
131Where <user> is the username of the person who is being granted root access. For instance:
132
133      permit jesse as root
134
135Additional users can be added to the file, one per line.
136
137Please note that a shell script, vidoas, is included with the doas program. The vidoas
138script must be run as the root user and will perform a syntax check on the doas.conf
139file before installing it on the system. This avoids breaking the doas.conf file. The
140vidoas script accepts no parameters and can be simply run as
141
142      vidoas
143
144## Desktop applications (GUI applications)
145
146Please be aware that, by default, doas scrubs most environment variables. In effect
147this means certain information about your environment will not be passed to the target
148user and graphical desktop applications (GUI applications) will not be able to run.
149To enable graphical applications to run from doas, please use the keepenv keyword
150in the configuration file. See the doas.conf manual page for details.
151
152## Running commands using doas
153
154To make use of doas, run it in front of any command. Here are some examples:
155
156Confirm doas is working by printing our effective user ID:
157
158     doas id
159
160Create a new file in the root user's home:
161
162     doas touch /root/new-file
163
164Edit a text file which requires admin access without running the text editor
165as the root user:
166
167     doasedit /path/to/text/file
168
169On 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:
170
171     doas -- rm -rf old-directory
172
173## Contributing
174
175Contributions, in various forms, are always welcome. If you run into a problem or have an improvement you'd like to see included, please 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.
176
177Financial 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.
178