README.md 12.4 KB
Newer Older
Tim Smith's avatar
Tim Smith committed
1
# sudo cookbook
Tim Smith's avatar
Tim Smith committed
2

Tim Smith's avatar
Tim Smith committed
3
[![Build Status](https://travis-ci.org/chef-cookbooks/sudo.svg?branch=master)](http://travis-ci.org/chef-cookbooks/sudo) [![Cookbook Version](https://img.shields.io/cookbook/v/sudo.svg)](https://supermarket.chef.io/cookbooks/sudo)
4

Tim Smith's avatar
Tim Smith committed
5
The default recipe configures the `/etc/sudoers` file. The cookbook also includes a sudo resource to adding and removing individual sudo entries.
jtimberman's avatar
jtimberman committed
6

7 8
NOTE: The `sudo` resource is now built into Chef 14+. When Chef 15 is released (April 2019) this resource will be removed from this cookbook as all users should be on Chef 14+.

Tim Smith's avatar
Tim Smith committed
9
## Requirements
Tim Smith's avatar
Tim Smith committed
10

Tim Smith's avatar
Tim Smith committed
11
### Platforms
Tim Smith's avatar
Tim Smith committed
12

13
- AIX
14 15
- Debian/Ubuntu
- RHEL/CentOS/Scientific/Amazon/Oracle
16
- Amazon Linux
17
- FreeBSD
18 19
- macOS
- openSUSE / SUSE Enterprise
Bryan Berry's avatar
Bryan Berry committed
20

Tim Smith's avatar
Tim Smith committed
21
### Chef
Tim Smith's avatar
Spacing  
Tim Smith committed
22

Tim Smith's avatar
Tim Smith committed
23
- Chef 12.21.3+
24

Tim Smith's avatar
Tim Smith committed
25
### Cookbooks
Tim Smith's avatar
Tim Smith committed
26

27
- None
Seth Vargo's avatar
Seth Vargo committed
28

29
## Resource
Tim Smith's avatar
Tim Smith committed
30

31 32
Use the sudo resource to add or remove individual sudo entries using sudoers.d files.

Tim Smith's avatar
Tim Smith committed
33 34
**Note** Sudo version 1.7.2 or newer is required to use the sudo resource as it relies on the "#includedir" directive introduced in version 1.7.2\. The resource does not enforce installing the version. Supported releases of Ubuntu, Debian and RHEL (6+) all support this feature.

35 36 37 38 39 40 41
### Actions

- `:create` - Create a sudoers config
- `:delete` - Delete a sudoers config

### Properties

Tim Smith's avatar
Tim Smith committed
42 43 44
Property            | Description                                                                                                                                                                                              | Example Value                            | Default Value
------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------
`filename`          | name of the `/etc/sudoers.d` file                                                                                                                                                                        | restart-tomcat                           | resource's name
45
`commands`          | array of commands this sudoer can execute, they must contain a full path. Example: use `/usr/bin/tail` over `tail`                                                                                                                                                                | ['/etc/init.d/tomcat restart']           | ['ALL']
Tim Smith's avatar
Tim Smith committed
46 47 48 49 50 51 52 53 54 55 56
`groups`            | group(s) to provide sudo privileges to. This accepts either an array or a comma separated list. Leading % on group names is optional. This property was named 'group' prior to the 5.1 cookbook release. | %admin,superadmin                        | []
`nopasswd`          | allow running sudo without specifying a password sudo                                                                                                                                                    | true                                     | false
`noexec`            | prevents commands from shelling out                                                                                                                                                                      | true                                     | false
`runas`             | User the command(s) can be run as                                                                                                                                                                        | root                                     | ALL
`template`          | the erb template to render instead of the default                                                                                                                                                        | restart-tomcat.erb                       |
`users`             | user(s) to provide sudo privileges to. This accepts either an array or a comma separated. This property was named 'user' prior to the 5.1 cookbook release. list.                                        | [tomcat, webapp]                         | []
`defaults`          | array of defaults this user has                                                                                                                                                                          | ['!requiretty','env_reset']              |
`setenv`            | whether to permit the preserving of environment with `sudo -E`                                                                                                                                           | true                                     | false
`env_keep_add`      | array of strings to add to env_keep                                                                                                                                                                      | ['HOME', 'MY_ENV_VAR MY_OTHER_ENV_VAR']  |
`env_keep_subtract` | array of strings to remove from env_keep                                                                                                                                                                 | ['DISPLAY', 'MY_SECURE_ENV_VAR']         |
`variables`         | the variables to pass to the custom template. Ignored if not using a custom template.                                                                                                                    | commands: ['/etc/init.d/tomcat restart'] |
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78

**If you use the template property, all other properties will be ignored except for the variables property.**

### Examples

#### user bob sudo privileges for any command

```ruby
sudo 'bob' do
  user 'bob'
end
```

#### group sysadmin passwordless sudo privileges for any command

```ruby
sudo "sysadmin" do
  group "sysadmin"
  nopasswd true
end
```

Tim Smith's avatar
Tim Smith committed
79 80 81 82 83 84 85 86 87 88
#### group sysadmin/superadmin and user bob passwordless sudo privileges for any command

```ruby
sudo "sysadmin" do
  group ['sysadmin', 'superadmin']
  user "bob"
  nopasswd true
end
```

89 90 91
### Built-In vs. Provided Templates

The resource provides two methods for templating the sudoers config files:
Tim Smith's avatar
Tim Smith committed
92 93 94 95

1. Using the built-in template
2. Using a custom, cookbook-level template

96
Both methods will create the `/etc/sudoers.d/#{resourcename}` files with the correct permissions.
Tim Smith's avatar
Tim Smith committed
97

Tim Smith's avatar
Tim Smith committed
98
The resource also performs **fragment validation**. If a sudoer-fragment is not valid, the Chef run will throw an exception and fail. This ensures that your sudoers file is always valid and cannot become corrupt (from this cookbook).
Tim Smith's avatar
Tim Smith committed
99

100
#### Using the Built-in Template
Tim Smith's avatar
Tim Smith committed
101 102 103

```ruby
sudo 'tomcat' do
Tim Smith's avatar
Tim Smith committed
104
  user      '%tomcat'    # or a username
Tim Smith's avatar
Tim Smith committed
105 106 107 108 109
  runas     'app_user'   # or 'app_user:tomcat'
  commands  ['/etc/init.d/tomcat restart']
end
```

110 111
#### Specifying Your Own Template

Tim Smith's avatar
Tim Smith committed
112 113 114
```ruby
sudo 'tomcat' do
  template    'my_tomcat.erb' # local cookbook template
Tim Smith's avatar
Tim Smith committed
115
  variables   cmds: ['/etc/init.d/tomcat restart']
Tim Smith's avatar
Tim Smith committed
116 117 118 119 120 121 122 123 124 125 126 127
end
```

In either case, the following file would be generated in `/etc/sudoers.d/tomcat`

```bash
# This file is managed by Chef for node.example.com
# Do NOT modify this file directly.

%tomcat ALL=(app_user) /etc/init.d/tomcat restart
```

128 129 130 131 132
## Usage

We highly recommend using the sudo resource to define individual sudo entries, but this cookbook also ships with a recipe that can be included on a run_list and controlled using attributes.

### Attributes
Tim Smith's avatar
Tim Smith committed
133

134
- `node['authorization']['sudo']['groups']` - groups to enable sudo access (default: `[]`)
Seth Vargo's avatar
Seth Vargo committed
135 136
- `node['authorization']['sudo']['users']` - users to enable sudo access (default: `[]`)
- `node['authorization']['sudo']['passwordless']` - use passwordless sudo (default: `false`)
137
- `node['authorization']['sudo']['include_sudoers_d']` - include and manage `/etc/sudoers.d` (default: `true` on Linux systems. Note: older / EOL distros do not support this feature)
Seth Vargo's avatar
Seth Vargo committed
138
- `node['authorization']['sudo']['agent_forwarding']` - preserve `SSH_AUTH_SOCK` when sudoing (default: `false`)
139
- `node['authorization']['sudo']['sudoers_defaults']` - Array of `Defaults` entries to configure in `/etc/sudoers`
140
- `node['authorization']['sudo']['setenv']` - Whether to permit preserving of environment with `sudo -E` (default: `false`)
jtimberman's avatar
jtimberman committed
141

142
### Using the Attributes
Tim Smith's avatar
Tim Smith committed
143

Seth Vargo's avatar
Seth Vargo committed
144
To use attributes for defining sudoers, set the attributes above on the node (or role) itself:
jtimberman's avatar
jtimberman committed
145

Seth Vargo's avatar
Seth Vargo committed
146 147 148
```json
{
  "default_attributes": {
jtimberman's avatar
jtimberman committed
149 150
    "authorization": {
      "sudo": {
Seth Vargo's avatar
Seth Vargo committed
151 152 153
        "groups": ["admin", "wheel", "sysadmin"],
        "users": ["jerry", "greg"],
        "passwordless": "true"
jtimberman's avatar
jtimberman committed
154 155
      }
    }
Seth Vargo's avatar
Seth Vargo committed
156 157 158 159
  }
}
```

160 161 162 163 164
```json
{
  "default_attributes": {
    "authorization": {
      "sudo": {
Jeremy J. Miller's avatar
Jeremy J. Miller committed
165
        "command_aliases": [{
166 167 168 169
          "name": "TEST",
          "command_list": [
            "/usr/bin/ls",
            "/usr/bin/cat"
170
          ]
Jeremy J. Miller's avatar
Jeremy J. Miller committed
171
        }],
172
        "custom_commands": {
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
          "users": [
            {
              "user": "test_user",
              "passwordless": true,
              "command_list": [
                "TEST"
              ]
            }
          ],
          "groups": [
            {
              "group": "test_group",
              "passwordless": false,
              "command_list": [
                "TEST"
              ]
            }
          ]
191 192 193 194 195 196 197
        }
      }
    }
  }
}
```

Seth Vargo's avatar
Seth Vargo committed
198 199 200 201 202 203 204 205 206 207 208 209
```ruby
# roles/example.rb
default_attributes(
  "authorization" => {
    "sudo" => {
      "groups" => ["admin", "wheel", "sysadmin"],
      "users" => ["jerry", "greg"],
      "passwordless" => true
    }
  }
)
```
jtimberman's avatar
jtimberman committed
210

Seth Vargo's avatar
Seth Vargo committed
211
**Note that the template for the sudoers file has the group "sysadmin" with ALL:ALL permission, though the group by default does not exist.**
jtimberman's avatar
jtimberman committed
212

Tim Smith's avatar
Tim Smith committed
213
### Sudoers Defaults
Tim Smith's avatar
Tim Smith committed
214

Tim Smith's avatar
Tim Smith committed
215
Configure a node attribute, `node['authorization']['sudo']['sudoers_defaults']` as an array of `Defaults` entries to configure in `/etc/sudoers`. A list of examples for common platforms is listed below:
216

Tim Smith's avatar
Tim Smith committed
217
_Debian_
218

Seth Vargo's avatar
Seth Vargo committed
219 220 221
```ruby
node.default['authorization']['sudo']['sudoers_defaults'] = ['env_reset']
```
222

Tim Smith's avatar
Tim Smith committed
223
_Ubuntu_
Tim Smith's avatar
Tim Smith committed
224

Seth Vargo's avatar
Seth Vargo committed
225 226 227 228 229 230
```ruby
node.default['authorization']['sudo']['sudoers_defaults'] = [
  'env_reset',
  'secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"'
]
```
231

Tim Smith's avatar
Tim Smith committed
232 233
_FreeBSD_

Craig Lewis's avatar
Craig Lewis committed
234 235 236 237 238 239 240
```ruby
node.default['authorization']['sudo']['sudoers_defaults'] = [
  'env_reset',
  'secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"'
]
```

Tim Smith's avatar
Tim Smith committed
241 242
_RHEL family 6.x_

Seth Vargo's avatar
Seth Vargo committed
243 244 245 246 247 248 249 250 251 252 253 254 255 256
```ruby
node.default['authorization']['sudo']['sudoers_defaults'] = [
  '!visiblepw',
  'env_reset',
  'env_keep =  "COLORS DISPLAY HOSTNAME HISTSIZE INPUTRC KDEDIR LS_COLORS"',
  'env_keep += "MAIL PS1 PS2 QTDIR USERNAME LANG LC_ADDRESS LC_CTYPE"',
  'env_keep += "LC_COLLATE LC_IDENTIFICATION LC_MEASUREMENT LC_MESSAGES"',
  'env_keep += "LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER LC_TELEPHONE"',
  'env_keep += "LC_TIME LC_ALL LANGUAGE LINGUAS _XKB_CHARSET XAUTHORITY"',
  'env_keep += "HOME"',
  'always_set_home',
  'secure_path = /sbin:/bin:/usr/sbin:/usr/bin'
]
```
Bryan Berry's avatar
Bryan Berry committed
257

Tim Smith's avatar
Tim Smith committed
258
_macOS_
Tim Smith's avatar
Tim Smith committed
259

260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
```ruby
node.default['authorization']['sudo']['sudoers_defaults'] = [
  'env_reset',
  'env_keep += "BLOCKSIZE"',
  'env_keep += "COLORFGBG COLORTERM"',
  'env_keep += "__CF_USER_TEXT_ENCODING"',
  'env_keep += "CHARSET LANG LANGUAGE LC_ALL LC_COLLATE LC_CTYPE"',
  'env_keep += "LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME"',
  'env_keep += "LINES COLUMNS"',
  'env_keep += "LSCOLORS"',
  'env_keep += "TZ"',
  'env_keep += "DISPLAY XAUTHORIZATION XAUTHORITY"',
  'env_keep += "EDITOR VISUAL"',
  'env_keep += "HOME MAIL"'
]
```

277
## Maintainers
Tim Smith's avatar
Tim Smith committed
278

279
This cookbook is maintained by Chef's Community Cookbook Engineering team. Our goal is to improve cookbook quality and to aid the community in contributing to cookbooks. To learn more about our team, process, and design goals see our [team documentation](https://github.com/chef-cookbooks/community_cookbook_documentation/blob/master/COOKBOOK_TEAM.MD). To learn more about contributing to cookbooks like this see our [contributing documentation](https://github.com/chef-cookbooks/community_cookbook_documentation/blob/master/CONTRIBUTING.MD), or if you have general questions about this cookbook come chat with us in #cookbok-engineering on the [Chef Community Slack](http://community-slack.chef.io/)
280

281
## License
jtimberman's avatar
jtimberman committed
282

Tim Smith's avatar
Tim Smith committed
283
**Copyright:** 2008-2018, Chef Software, Inc.
Tim Smith's avatar
Tim Smith committed
284

285
```
jtimberman's avatar
jtimberman committed
286 287 288 289 290 291 292 293 294 295 296
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Seth Vargo's avatar
Seth Vargo committed
297
```