granicus.if.org Git - sudo/blob - doc/cvtsudoers.man.in

   1 .\" Automatically generated from an mdoc input file.  Do not edit.
   2 .\"
   3 .\" Copyright (c) 2018 Todd C. Miller <Todd.Miller@sudo.ws>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .TH "CVTSUDOERS" "1" "December 11, 2018" "Sudo @PACKAGE_VERSION@" "General Commands Manual"
  18 .nh
  19 .if n .ad l
  20 .SH "NAME"
  21 \fBcvtsudoers\fR
  22 \- convert between sudoers file formats
  23 .SH "SYNOPSIS"
  24 .HP 11n
  25 \fBcvtsudoers\fR
  26 [\fB\-ehMpV\fR]
  27 [\fB\-b\fR\ \fIdn\fR]
  28 [\fB\-c\fR\ \fIconf_file\fR]
  29 [\fB\-d\fR\ \fIdeftypes\fR]
  30 [\fB\-f\fR\ \fIoutput_format\fR]
  31 [\fB\-i\fR\ \fIinput_format\fR]
  32 [\fB\-I\fR\ \fIincrement\fR]
  33 [\fB\-m\fR\ \fIfilter\fR]
  34 [\fB\-o\fR\ \fIoutput_file\fR]
  35 [\fB\-O\fR\ \fIstart_point\fR]
  36 [\fB\-P\fR\ \fIpadding\fR]
  37 [\fB\-s\fR\ \fIsections\fR]
  38 [\fIinput_file\fR]
  39 .SH "DESCRIPTION"
  40 \fBcvtsudoers\fR
  41 can be used to convert between
  42 \fIsudoers\fR
  43 security policy file formats.
  44 The default input format is sudoers.
  45 The default output format is LDIF.
  46 It is only possible to convert a
  47 \fIsudoers\fR
  48 file that is syntactically correct.
  49 .PP
  50 If no
  51 \fIinput_file\fR
  52 is specified, or if it is
  53 \(oq-\(cq,
  54 the policy is read from the standard input.
  55 By default, the result is written to the standard output.
  56 .PP
  57 The options are as follows:
  58 .TP 12n
  59 \fB\-b\fR \fIdn\fR, \fB\--base\fR=\fIdn\fR
  60 The base DN (distinguished name) that will be used when performing
  61 LDAP queries.
  62 Typically this is of the form
  63 \fRou=SUDOers,dc=my-domain,dc=com\fR
  64 for the domain
  65 \fRmy-domain.com\fR.
  66 If this option is not specified, the value of the
  67 \fRSUDOERS_BASE\fR
  68 environment variable will be used instead.
  69 Only necessary when converting to LDIF format.
  70 .TP 12n
  71 \fB\-c\fR \fIconf_file\fR, \fB\--config\fR=\fIconf_file\fR
  72 Specify the path to the configuration file.
  73 Defaults to
  74 \fI@sysconfdir@/cvtsudoers.conf\fR.
  75 .TP 12n
  76 \fB\-d\fR \fIdeftypes\fR, \fB\--defaults\fR=\fIdeftypes\fR
  77 Only convert
  78 \fRDefaults\fR
  79 entries of the specified types.
  80 One or more
  81 \fRDefaults\fR
  82 types may be specified, separated by a comma
  83 (\(oq\&,\(cq).
  84 The supported types are:
  85 .PP
  86 .RS 12n
  87 .PD 0
  88 .TP 10n
  89 all
  90 All Defaults entries.
  91 .PD
  92 .TP 10n
  93 global
  94 Global Defaults entries that are applied regardless of
  95 user, runas, host or command.
  96 .TP 10n
  97 user
  98 Per-user Defaults entries.
  99 .TP 10n
 100 runas
 101 Per-runas user Defaults entries.
 102 .TP 10n
 103 host
 104 Per-host Defaults entries.
 105 .TP 10n
 106 command
 107 Per-command Defaults entries.
 108 .PP
 109 See the
 110 \fBDefaults\fR
 111 section in
 112 sudoers(@mansectform@)
 113 for more information.
 114 .sp
 115 If the
 116 \fB\-d\fR
 117 option is not specified, all
 118 \fRDefaults\fR
 119 entries will be converted.
 120 .RE
 121 .TP 12n
 122 \fB\-e\fR, \fB\--expand-aliases\fR
 123 Expand aliases in
 124 \fIinput_file\fR.
 125 Aliases are preserved by default when the output
 126 \fIformat\fR
 127 is JSON or sudoers.
 128 .TP 12n
 129 \fB\-f\fR \fIoutput_format\fR, \fB\--output-format\fR=\fIoutput_format\fR
 130 Specify the output format (case-insensitive).
 131 The following formats are supported:
 132 .PP
 133 .RS 12n
 134 .PD 0
 135 .TP 10n
 136 JSON
 137 JSON (JavaScript Object Notation) files are usually easier for
 138 third-party applications to consume than the traditional
 139 \fIsudoers\fR
 140 format.
 141 The various values have explicit types which removes much of the
 142 ambiguity of the
 143 \fIsudoers\fR
 144 format.
 145 .PD
 146 .TP 10n
 147 LDIF
 148 LDIF (LDAP Data Interchange Format) files can be imported into an LDAP
 149 server for use with
 150 sudoers.ldap(@mansectform@).
 151 .sp
 152 Conversion to LDIF has the following limitations:
 153 .PP
 154 .RS 10n
 155 .PD 0
 156 .TP 3n
 157 \fB\(bu\fR
 158 Command, host, runas and user-specific Defaults lines cannot be
 159 translated as they don't have an equivalent in the sudoers LDAP schema.
 160 .PD
 161 .TP 3n
 162 \fB\(bu\fR
 163 Command, host, runas and user aliases are not supported by the
 164 sudoers LDAP schema so they are expanded during the conversion.
 165 .PD 0
 166 .PP
 167 .RE
 168 .PD
 169 .TP 10n
 170 sudoers
 171 Traditional sudoers format.
 172 A new sudoers file will be reconstructed from the parsed input file.
 173 Comments are not preserved and data from any include files will be
 174 output inline.
 175 .PD 0
 176 .PP
 177 .RE
 178 .PD
 179 .TP 12n
 180 \fB\-h\fR, \fB\--help\fR
 181 Display a short help message to the standard output and exit.
 182 .TP 12n
 183 \fB\-i\fR \fIinput_format\fR, \fB\--input-format\fR=\fIinput_format\fR
 184 Specify the input format.
 185 The following formats are supported:
 186 .PP
 187 .RS 12n
 188 .PD 0
 189 .TP 10n
 190 LDIF
 191 LDIF (LDAP Data Interchange Format) files can be exported from an LDAP
 192 server to convert security policies used by
 193 sudoers.ldap(@mansectform@).
 194 If a base DN (distinguished name) is specified, only sudoRole objects
 195 that match the base DN will be processed.
 196 Not all sudoOptions specified in a sudoRole can be translated from
 197 LDIF to sudoers format.
 198 .PD
 199 .TP 10n
 200 sudoers
 201 Traditional sudoers format.
 202 This is the default input format.
 203 .PD 0
 204 .PP
 205 .RE
 206 .PD
 207 .TP 12n
 208 \fB\-I\fR \fIincrement\fR, \fB\--increment\fR=\fIincrement\fR
 209 When generating LDIF output, increment each sudoOrder attribute by
 210 the specified number.
 211 Defaults to an increment of 1.
 212 .TP 12n
 213 \fB\-m\fR \fIfilter\fR, \fB\--match\fR=\fIfilter\fR
 214 Only output rules that match the specified
 215 \fIfilter\fR.
 216 A
 217 \fIfilter\fR
 218 expression is made up of one or more
 219 \fBkey =\fR \fIvalue\fR
 220 pairs, separated by a comma
 221 (\(oq\&,\(cq).
 222 The
 223 \fBkey\fR
 224 may be
 225 \(lquser\(rq,
 226 \(lqgroup\(rq
 227 or
 228 \(lqhost\(rq.
 229 For example,
 230 \fBuser\fR = \fIoperator\fR
 231 or
 232 \fBhost\fR = \fIwww\fR.
 233 An upper-case User_Alias or Host_Alias may be specified as the
 234 \(lquser\(rq
 235 or
 236 \(lqhost\(rq.
 237 .sp
 238 A matching
 239 \fIsudoers\fR
 240 rule may also include users, groups and hosts that are not part of the
 241 \fIfilter\fR.
 242 This can happen when a rule includes multiple users, groups or hosts.
 243 To prune out any non-matching user, group or host from the rules, the
 244 \fB\-p\fR
 245 option may be used.
 246 .sp
 247 By default, the password and group databases are not consulted when matching
 248 against the filter so the users and groups do not need to be present
 249 on the local system (see the
 250 \fB\-M\fR
 251 option).
 252 Only aliases that are referenced by the filtered policy rules will
 253 be displayed.
 254 .TP 12n
 255 \fB\-M\fR, \fB\--match-local\fR
 256 When the
 257 \fB\-m\fR
 258 option is also specified, use password and group database information
 259 when matching users and groups in the filter.
 260 Only users and groups in the filter that exist on the local system will match,
 261 and a user's groups will automatically be added to the filter.
 262 If the
 263 \fB\-M\fR
 264 is
 265 \fInot\fR
 266 specified, users and groups in the filter do not need to exist on the
 267 local system, but all groups used for matching must be explicitly listed
 268 in the filter.
 269 .TP 12n
 270 \fB\-o\fR \fIoutput_file\fR, \fB\--output\fR=\fIoutput_file\fR
 271 Write the converted output to
 272 \fIoutput_file\fR.
 273 If no
 274 \fIoutput_file\fR
 275 is specified, or if it is
 276 \(oq-\(cq,
 277 the converted
 278 \fIsudoers\fR
 279 policy will be written to the standard output.
 280 .TP 12n
 281 \fB\-O\fR \fIstart_point\fR, \fB\--order-start\fR=\fIstart_point\fR
 282 When generating LDIF output, use the number specified by
 283 \fIstart_point\fR
 284 in the sudoOrder attribute of the first sudoRole object.
 285 Subsequent sudoRole object use a sudoOrder value generated by adding an
 286 \fIincrement\fR,
 287 see the
 288 \fB\-I\fR
 289 option for details.
 290 Defaults to a starting point of 1.
 291 A starting point of 0 will disable the generation of sudoOrder
 292 attributes in the resulting LDIF file.
 293 .TP 12n
 294 \fB\-p\fR, \fB\--prune-matches\fR
 295 When the
 296 \fB\-m\fR
 297 option is also specified,
 298 \fBcvtsudoers\fR
 299 will prune out non-matching users, groups and hosts from
 300 matching entries.
 301 .TP 12n
 302 \fB\-P\fR \fIpadding\fR, \fB\--padding\fR=\fIpadding\fR
 303 When generating LDIF output, construct the initial sudoOrder value by
 304 concatenating
 305 \fIorder_start\fR
 306 and
 307 \fIincrement\fR,
 308 padding the
 309 \fIincrement\fR
 310 with zeros until it consists of
 311 \fIpadding\fR
 312 digits.
 313 For example, if
 314 \fIorder_start\fR
 315 is 1027,
 316 \fIpadding\fR
 317 is 3, and
 318 \fIincrement\fR
 319 is 1, the value of sudoOrder for the first entry will be 1027000,
 320 followed by 1027001, 1027002, etc.
 321 If the number of sudoRole entries is larger than the padding would allow,
 322 \fBcvtsudoers\fR
 323 will exit with an error.
 324 By default, no padding is performed.
 325 .TP 12n
 326 \fB\-s\fR \fIsections\fR, \fB\--suppress\fR=\fIsections\fR
 327 Suppress the output of specific
 328 \fIsections\fR
 329 of the security policy.
 330 One or more section names may be specified, separated by a comma
 331 (\(oq\&,\(cq).
 332 The supported section name are:
 333 \fBdefaults\fR,
 334 \fBaliases\fR
 335 and
 336 \fBprivileges\fR
 337 (which may be shortened to
 338 \fBprivs\fR).
 339 .TP 12n
 340 \fB\-V\fR, \fB\--version\fR
 341 Print the
 342 \fBcvtsudoers\fR
 343 and
 344 \fIsudoers\fR
 345 grammar versions and exit.
 346 .PP
 347 Options in the form
 348 \(lqkeyword = value\(rq
 349 may also be specified in a configuration file,
 350 \fI@sysconfdir@/cvtsudoers.conf\fR
 351 by default.
 352 The following keywords are recognized:
 353 .TP 6n
 354 \fBdefaults =\fR \fIdeftypes\fR
 355 See the description of the
 356 \fB\-d\fR
 357 command line option.
 358 .TP 6n
 359 \fBexpand_aliases =\fR \fIyes\fR | \fIno\fR
 360 See the description of the
 361 \fB\-e\fR
 362 command line option.
 363 .TP 6n
 364 \fBinput_format =\fR \fIldif\fR | \fIsudoers\fR
 365 See the description of the
 366 \fB\-i\fR
 367 command line option.
 368 .TP 6n
 369 \fBmatch =\fR \fIfilter\fR
 370 See the description of the
 371 \fB\-m\fR
 372 command line option.
 373 .TP 6n
 374 \fBorder_increment =\fR \fIincrement\fR
 375 See the description of the
 376 \fB\-I\fR
 377 command line option.
 378 .TP 6n
 379 \fBorder_start =\fR \fIstart_point\fR
 380 See the description of the
 381 \fB\-O\fR
 382 command line option.
 383 .TP 6n
 384 \fBoutput_format =\fR \fIjson\fR | \fIldif\fR | \fIsudoers\fR
 385 See the description of the
 386 \fB\-f\fR
 387 command line option.
 388 .TP 6n
 389 \fBpadding =\fR \fIpadding\fR
 390 See the description of the
 391 \fB\-P\fR
 392 command line option.
 393 .TP 6n
 394 \fBprune_matches =\fR \fIyes\fR | \fIno\fR
 395 See the description of the
 396 \fB\-p\fR
 397 command line option.
 398 .TP 6n
 399 \fBsudoers_base =\fR \fIdn\fR
 400 See the description of the
 401 \fB\-b\fR
 402 command line option.
 403 .TP 6n
 404 \fBsuppress =\fR \fIsections\fR
 405 See the description of the
 406 \fB\-s\fR
 407 command line option.
 408 .PP
 409 Options on the command line will override values from the
 410 configuration file.
 411 .SH "FILES"
 412 .TP 26n
 413 \fI@sysconfdir@/cvtsudoers.conf\fR
 414 default configuration for cvtsudoers
 415 .SH "EXAMPLES"
 416 Convert
 417 \fI/etc/sudoers\fR
 418 to LDIF (LDAP Data Interchange Format) where the
 419 \fIldap.conf\fR
 420 file uses a
 421 \fIsudoers_base\fR
 422 of my-domain,dc=com, storing the result in
 423 \fIsudoers.ldif\fR:
 424 .nf
 425 .sp
 426 .RS 6n
 427 $ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \e
 428              /etc/sudoers
 429 .RE
 430 .fi
 431 .PP
 432 Convert
 433 \fI/etc/sudoers\fR
 434 to JSON format, storing the result in
 435 \fIsudoers.json\fR:
 436 .nf
 437 .sp
 438 .RS 6n
 439 $ cvtsudoers -f json -o sudoers.json /etc/sudoers
 440 .RE
 441 .fi
 442 .PP
 443 Parse
 444 \fI/etc/sudoers\fR
 445 and display only rules that match user
 446 \fIambrose\fR
 447 on host
 448 \fIhastur\fR:
 449 .nf
 450 .sp
 451 .RS 6n
 452 $ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers
 453 .RE
 454 .fi
 455 .PP
 456 Same as above, but expand aliases and prune out any non-matching
 457 users and hosts from the expanded entries.
 458 .nf
 459 .sp
 460 .RS 6n
 461 $ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers
 462 .RE
 463 .fi
 464 .PP
 465 Convert
 466 \fIsudoers.ldif\fR
 467 from LDIF to traditional
 468 \fIsudoers\fR
 469 format:
 470 .nf
 471 .sp
 472 .RS 6n
 473 $ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif
 474 .RE
 475 .fi
 476 .SH "SEE ALSO"
 477 sudoers(@mansectform@),
 478 sudoers.ldap(@mansectform@),
 479 sudo(@mansectsu@)
 480 .SH "AUTHORS"
 481 Many people have worked on
 482 \fBsudo\fR
 483 over the years; this version consists of code written primarily by:
 484 .sp
 485 .RS 6n
 486 Todd C. Miller
 487 .RE
 488 .PP
 489 See the CONTRIBUTORS file in the
 490 \fBsudo\fR
 491 distribution (https://www.sudo.ws/contributors.html) for an
 492 exhaustive list of people who have contributed to
 493 \fBsudo\fR.
 494 .SH "BUGS"
 495 If you feel you have found a bug in
 496 \fBcvtsudoers\fR,
 497 please submit a bug report at https://bugzilla.sudo.ws/
 498 .SH "SUPPORT"
 499 Limited free support is available via the sudo-users mailing list,
 500 see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 501 search the archives.
 502 .SH "DISCLAIMER"
 503 \fBcvtsudoers\fR
 504 is provided
 505 \(lqAS IS\(rq
 506 and any express or implied warranties, including, but not limited
 507 to, the implied warranties of merchantability and fitness for a
 508 particular purpose are disclaimed.
 509 See the LICENSE file distributed with
 510 \fBsudo\fR
 511 or https://www.sudo.ws/license.html for complete details.