granicus.if.org Git - apache/blob - docs/manual/suexec.html.en

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3
   4 <html xmlns="http://www.w3.org/1999/xhtml">
   5   <head>
   6     <meta name="generator" content="HTML Tidy, see www.w3.org" />
   7
   8     <title>Apache suEXEC Support</title>
   9   </head>
  10   <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  11
  12   <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
  13   vlink="#000080" alink="#FF0000">
  14     <!--#include virtual="header.html" -->
  15
  16     <h1 align="CENTER">Apache suEXEC Support</h1>
  17
  18     <ol>
  19       <li><big><strong>CONTENTS</strong></big></li>
  20
  21       <li><a href="#what">What is suEXEC?</a></li>
  22
  23       <li><a href="#before">Before we begin.</a></li>
  24
  25       <li><a href="#model">suEXEC Security Model.</a></li>
  26
  27       <li><a href="#install">Configuring &amp; Installing
  28       suEXEC</a></li>
  29
  30       <li><a href="#enable">Enabling &amp; Disabling
  31       suEXEC</a></li>
  32
  33       <li><a href="#usage">Using suEXEC</a></li>
  34
  35       <li><a href="#debug">Debugging suEXEC</a></li>
  36
  37       <li><a href="#jabberwock">Beware the Jabberwock: Warnings
  38       &amp; Examples</a></li>
  39     </ol>
  40     <br />
  41      <br />
  42
  43
  44     <h3><a id="what" name="what">What is suEXEC?</a></h3>
  45
  46     <p align="LEFT">The <strong>suEXEC</strong> feature --
  47     introduced in Apache 1.2 -- provides Apache users the ability
  48     to run <strong>CGI</strong> and <strong>SSI</strong> programs
  49     under user IDs different from the user ID of the calling
  50     web-server. Normally, when a CGI or SSI program executes, it
  51     runs as the same user who is running the web server.</p>
  52
  53     <p align="LEFT">Used properly, this feature can reduce
  54     considerably the security risks involved with allowing users to
  55     develop and run private CGI or SSI programs. However, if suEXEC
  56     is improperly configured, it can cause any number of problems
  57     and possibly create new holes in your computer's security. If
  58     you aren't familiar with managing setuid root programs and the
  59     security issues they present, we highly recommend that you not
  60     consider using suEXEC.</p>
  61
  62     <p align="CENTER"><strong><a href="suexec.html">BACK TO
  63     CONTENTS</a></strong></p>
  64
  65     <h3><a id="before" name="before">Before we begin.</a></h3>
  66
  67     <p align="LEFT">Before jumping head-first into this document,
  68     you should be aware of the assumptions made on the part of the
  69     Apache Group and this document.</p>
  70
  71     <p align="LEFT">First, it is assumed that you are using a UNIX
  72     derivate operating system that is capable of
  73     <strong>setuid</strong> and <strong>setgid</strong> operations.
  74     All command examples are given in this regard. Other platforms,
  75     if they are capable of supporting suEXEC, may differ in their
  76     configuration.</p>
  77
  78     <p align="LEFT">Second, it is assumed you are familiar with
  79     some basic concepts of your computer's security and its
  80     administration. This involves an understanding of
  81     <strong>setuid/setgid</strong> operations and the various
  82     effects they may have on your system and its level of
  83     security.</p>
  84
  85     <p align="LEFT">Third, it is assumed that you are using an
  86     <strong>unmodified</strong> version of suEXEC code. All code
  87     for suEXEC has been carefully scrutinized and tested by the
  88     developers as well as numerous beta testers. Every precaution
  89     has been taken to ensure a simple yet solidly safe base of
  90     code. Altering this code can cause unexpected problems and new
  91     security risks. It is <strong>highly</strong> recommended you
  92     not alter the suEXEC code unless you are well versed in the
  93     particulars of security programming and are willing to share
  94     your work with the Apache Group for consideration.</p>
  95
  96     <p align="LEFT">Fourth, and last, it has been the decision of
  97     the Apache Group to <strong>NOT</strong> make suEXEC part of
  98     the default installation of Apache. To this end, suEXEC
  99     configuration requires of the administrator careful attention
 100     to details. After due consideration has been given to the
 101     various settings for suEXEC, the administrator may install
 102     suEXEC through normal installation methods. The values for
 103     these settings need to be carefully determined and specified by
 104     the administrator to properly maintain system security during
 105     the use of suEXEC functionality. It is through this detailed
 106     process that the Apache Group hopes to limit suEXEC
 107     installation only to those who are careful and determined
 108     enough to use it.</p>
 109
 110     <p align="LEFT">Still with us? Yes? Good. Let's move on!</p>
 111
 112     <p align="CENTER"><strong><a href="suexec.html">BACK TO
 113     CONTENTS</a></strong></p>
 114
 115     <h3><a id="model" name="model">suEXEC Security Model</a></h3>
 116
 117     <p align="LEFT">Before we begin configuring and installing
 118     suEXEC, we will first discuss the security model you are about
 119     to implement. By doing so, you may better understand what
 120     exactly is going on inside suEXEC and what precautions are
 121     taken to ensure your system's security.</p>
 122
 123     <p align="LEFT"><strong>suEXEC</strong> is based on a setuid
 124     "wrapper" program that is called by the main Apache web server.
 125     This wrapper is called when an HTTP request is made for a CGI
 126     or SSI program that the administrator has designated to run as
 127     a userid other than that of the main server. When such a
 128     request is made, Apache provides the suEXEC wrapper with the
 129     program's name and the user and group IDs under which the
 130     program is to execute.</p>
 131
 132     <p align="LEFT">The wrapper then employs the following process
 133     to determine success or failure -- if any one of these
 134     conditions fail, the program logs the failure and exits with an
 135     error, otherwise it will continue:</p>
 136
 137     <ol>
 138       <li>
 139         <strong>Was the wrapper called with the proper number of
 140         arguments?</strong>
 141
 142         <blockquote>
 143           The wrapper will only execute if it is given the proper
 144           number of arguments. The proper argument format is known
 145           to the Apache web server. If the wrapper is not receiving
 146           the proper number of arguments, it is either being
 147           hacked, or there is something wrong with the suEXEC
 148           portion of your Apache binary.
 149         </blockquote>
 150       </li>
 151
 152       <li>
 153         <strong>Is the user executing this wrapper a valid user of
 154         this system?</strong>
 155
 156         <blockquote>
 157           This is to ensure that the user executing the wrapper is
 158           truly a user of the system.
 159         </blockquote>
 160       </li>
 161
 162       <li>
 163         <strong>Is this valid user allowed to run the
 164         wrapper?</strong>
 165
 166         <blockquote>
 167           Is this user the user allowed to run this wrapper? Only
 168           one user (the Apache user) is allowed to execute this
 169           program.
 170         </blockquote>
 171       </li>
 172
 173       <li>
 174         <strong>Does the target program have an unsafe hierarchical
 175         reference?</strong>
 176
 177         <blockquote>
 178           Does the target program contain a leading '/' or have a
 179           '..' backreference? These are not allowed; the target
 180           program must reside within the Apache webspace.
 181         </blockquote>
 182       </li>
 183
 184       <li>
 185         <strong>Is the target user name valid?</strong>
 186
 187         <blockquote>
 188           Does the target user exist?
 189         </blockquote>
 190       </li>
 191
 192       <li>
 193         <strong>Is the target group name valid?</strong>
 194
 195         <blockquote>
 196           Does the target group exist?
 197         </blockquote>
 198       </li>
 199
 200       <li>
 201         <strong>Is the target user <em>NOT</em> superuser?</strong>
 202
 203
 204         <blockquote>
 205           Presently, suEXEC does not allow 'root' to execute
 206           CGI/SSI programs.
 207         </blockquote>
 208       </li>
 209
 210       <li>
 211         <strong>Is the target userid <em>ABOVE</em> the minimum ID
 212         number?</strong>
 213
 214         <blockquote>
 215           The minimum user ID number is specified during
 216           configuration. This allows you to set the lowest possible
 217           userid that will be allowed to execute CGI/SSI programs.
 218           This is useful to block out "system" accounts.
 219         </blockquote>
 220       </li>
 221
 222       <li>
 223         <strong>Is the target group <em>NOT</em> the superuser
 224         group?</strong>
 225
 226         <blockquote>
 227           Presently, suEXEC does not allow the 'root' group to
 228           execute CGI/SSI programs.
 229         </blockquote>
 230       </li>
 231
 232       <li>
 233         <strong>Is the target groupid <em>ABOVE</em> the minimum ID
 234         number?</strong>
 235
 236         <blockquote>
 237           The minimum group ID number is specified during
 238           configuration. This allows you to set the lowest possible
 239           groupid that will be allowed to execute CGI/SSI programs.
 240           This is useful to block out "system" groups.
 241         </blockquote>
 242       </li>
 243
 244       <li>
 245         <strong>Can the wrapper successfully become the target user
 246         and group?</strong>
 247
 248         <blockquote>
 249           Here is where the program becomes the target user and
 250           group via setuid and setgid calls. The group access list
 251           is also initialized with all of the groups of which the
 252           user is a member.
 253         </blockquote>
 254       </li>
 255
 256       <li>
 257         <strong>Does the directory in which the program resides
 258         exist?</strong>
 259
 260         <blockquote>
 261           If it doesn't exist, it can't very well contain files.
 262         </blockquote>
 263       </li>
 264
 265       <li>
 266         <strong>Is the directory within the Apache
 267         webspace?</strong>
 268
 269         <blockquote>
 270           If the request is for a regular portion of the server, is
 271           the requested directory within the server's document
 272           root? If the request is for a UserDir, is the requested
 273           directory within the user's document root?
 274         </blockquote>
 275       </li>
 276
 277       <li>
 278         <strong>Is the directory <em>NOT</em> writable by anyone
 279         else?</strong>
 280
 281         <blockquote>
 282           We don't want to open up the directory to others; only
 283           the owner user may be able to alter this directories
 284           contents.
 285         </blockquote>
 286       </li>
 287
 288       <li>
 289         <strong>Does the target program exist?</strong>
 290
 291         <blockquote>
 292           If it doesn't exists, it can't very well be executed.
 293         </blockquote>
 294       </li>
 295
 296       <li>
 297         <strong>Is the target program <em>NOT</em> writable by
 298         anyone else?</strong>
 299
 300         <blockquote>
 301           We don't want to give anyone other than the owner the
 302           ability to change the program.
 303         </blockquote>
 304       </li>
 305
 306       <li>
 307         <strong>Is the target program <em>NOT</em> setuid or
 308         setgid?</strong>
 309
 310         <blockquote>
 311           We do not want to execute programs that will then change
 312           our UID/GID again.
 313         </blockquote>
 314       </li>
 315
 316       <li>
 317         <strong>Is the target user/group the same as the program's
 318         user/group?</strong>
 319
 320         <blockquote>
 321           Is the user the owner of the file?
 322         </blockquote>
 323       </li>
 324
 325       <li>
 326         <strong>Can we successfully clean the process environment
 327         to ensure safe operations?</strong>
 328
 329         <blockquote>
 330           suEXEC cleans the process' environment by establishing a
 331           safe execution PATH (defined during configuration), as
 332           well as only passing through those variables whose names
 333           are listed in the safe environment list (also created
 334           during configuration).
 335         </blockquote>
 336       </li>
 337
 338       <li>
 339         <strong>Can we successfully become the target program and
 340         execute?</strong>
 341
 342         <blockquote>
 343           Here is where suEXEC ends and the target program begins.
 344         </blockquote>
 345       </li>
 346     </ol>
 347     <br />
 348      <br />
 349
 350
 351     <p align="LEFT">This is the standard operation of the the
 352     suEXEC wrapper's security model. It is somewhat stringent and
 353     can impose new limitations and guidelines for CGI/SSI design,
 354     but it was developed carefully step-by-step with security in
 355     mind.</p>
 356
 357     <p align="LEFT">For more information as to how this security
 358     model can limit your possibilities in regards to server
 359     configuration, as well as what security risks can be avoided
 360     with a proper suEXEC setup, see the <a
 361     href="#jabberwock">"Beware the Jabberwock"</a> section of this
 362     document.</p>
 363
 364     <p align="CENTER"><strong><a href="suexec.html">BACK TO
 365     CONTENTS</a></strong></p>
 366
 367     <h3><a id="install" name="install">Configuring &amp; Installing
 368     suEXEC</a></h3>
 369
 370     <p align="LEFT">Here's where we begin the fun. If you use
 371     Apache 1.2 or prefer to configure Apache 1.3 with the
 372     "<code>src/Configure</code>" script you have to edit the suEXEC
 373     header file and install the binary in its proper location
 374     manually. The following sections describe the configuration and
 375     installation for Apache 1.3 with the AutoConf-style interface
 376     (APACI).</p>
 377
 378     <p align="LEFT"><strong>APACI's suEXEC configuration
 379     options</strong><br />
 380     </p>
 381
 382     <dl>
 383       <dt><code>--enable-suexec</code></dt>
 384
 385       <dd>This option enables the suEXEC feature which is never
 386       installed or activated by default. At least one
 387       --with-suexec-xxxxx option has to be provided together with the
 388       --enable-suexec option to let APACI accept your request for
 389       using the suEXEC feature.</dd>
 390
 391       <dt><code>--with-suexec-caller=<em>UID</em></code></dt>
 392
 393       <dd>The <a href="mod/mpm_common.html#user">username</a> under which
 394       Apache normally runs. This is the only user allowed to
 395       execute this program.</dd>
 396
 397       <dt><code>--with-suexec-docroot=<em>DIR</em></code></dt>
 398
 399       <dd>Define as the DocumentRoot set for Apache. This will be
 400       the only hierarchy (aside from UserDirs) that can be used for
 401       suEXEC behavior. The default directory is the --datadir value
 402       with the suffix "/htdocs", <em>e.g.</em> if you configure
 403       with "<code>--datadir=/home/apache</code>" the directory
 404       "/home/apache/htdocs" is used as document root for the suEXEC
 405       wrapper.</dd>
 406
 407       <dt><code>--with-suexec-logfile=<em>FILE</em></code></dt>
 408
 409       <dd>This defines the filename to which all suEXEC
 410       transactions and errors are logged (useful for auditing and
 411       debugging purposes). By default the logfile is named
 412       "suexec_log" and located in your standard logfile directory
 413       (--logfiledir).</dd>
 414
 415       <dt><code>--with-suexec-userdir=<em>DIR</em></code></dt>
 416
 417       <dd>Define to be the subdirectory under users' home
 418       directories where suEXEC access should be allowed. All
 419       executables under this directory will be executable by suEXEC
 420       as the user so they should be "safe" programs. If you are
 421       using a "simple" UserDir directive (ie. one without a "*" in
 422       it) this should be set to the same value. suEXEC will not
 423       work properly in cases where the UserDir directive points to
 424       a location that is not the same as the user's home directory
 425       as referenced in the passwd file. Default value is
 426       "public_html".<br />
 427        If you have virtual hosts with a different UserDir for each,
 428       you will need to define them to all reside in one parent
 429       directory; then name that parent directory here. <strong>If
 430       this is not defined properly, "~userdir" cgi requests will
 431       not work!</strong></dd>
 432
 433       <dt><code>--with-suexec-uidmin=<em>UID</em></code></dt>
 434
 435       <dd>Define this as the lowest UID allowed to be a target user
 436       for suEXEC. For most systems, 500 or 100 is common. Default
 437       value is 100.</dd>
 438
 439       <dt><code>--with-suexec-gidmin=<em>GID</em></code></dt>
 440
 441       <dd>Define this as the lowest GID allowed to be a target
 442       group for suEXEC. For most systems, 100 is common and
 443       therefore used as default value.</dd>
 444
 445       <dt><code>--with-suexec-safepath=<em>PATH</em></code></dt>
 446
 447       <dd>Define a safe PATH environment to pass to CGI
 448       executables. Default value is
 449       "/usr/local/bin:/usr/bin:/bin".</dd>
 450     </dl>
 451     <br />
 452      <br />
 453
 454
 455     <p align="LEFT"><strong>Checking your suEXEC
 456     setup</strong><br />
 457      Before you compile and install the suEXEC wrapper you can
 458     check the configuration with the --layout option.<br />
 459      Example output:</p>
 460 <pre>
 461     suEXEC setup:
 462             suexec binary: /usr/local/apache/sbin/suexec
 463             document root: /usr/local/apache/share/htdocs
 464            userdir suffix: public_html
 465                   logfile: /usr/local/apache/var/log/suexec_log
 466                 safe path: /usr/local/bin:/usr/bin:/bin
 467                 caller ID: www
 468           minimum user ID: 100
 469          minimum group ID: 100
 470 </pre>
 471     <br />
 472      <br />
 473
 474
 475     <p align="LEFT"><strong>Compiling and installing the suEXEC
 476     wrapper</strong><br />
 477      If you have enabled the suEXEC feature with the
 478     --enable-suexec option the suexec binary (together with Apache
 479     itself) is automatically built if you execute the command
 480     "make".<br />
 481      After all components have been built you can execute the
 482     command "make install" to install them. The binary image
 483     "suexec" is installed in the directory defined by the --sbindir
 484     option. Default location is
 485     "/usr/local/apache/sbin/suexec".<br />
 486      Please note that you need <strong><em>root
 487     privileges</em></strong> for the installation step. In order
 488     for the wrapper to set the user ID, it must be installed as
 489     owner <code><em>root</em></code> and must have the setuserid
 490     execution bit set for file modes.</p>
 491
 492     <p align="CENTER"><strong><a href="suexec.html">BACK TO
 493     CONTENTS</a></strong></p>
 494
 495     <h3><a id="enable" name="enable">Enabling &amp; Disabling
 496     suEXEC</a></h3>
 497
 498     <p align="LEFT">Upon startup of Apache, it looks for the file
 499     "suexec" in the "sbin" directory (default is
 500     "/usr/local/apache/sbin/suexec"). If Apache finds a properly
 501     configured suEXEC wrapper, it will print the following message
 502     to the error log:</p>
 503 <pre>
 504     [notice] suEXEC mechanism enabled (wrapper: <em>/path/to/suexec</em>)
 505 </pre>
 506     If you don't see this message at server startup, the server is
 507     most likely not finding the wrapper program where it expects
 508     it, or the executable is not installed <em>setuid root</em>.
 509     <br />
 510      If you want to enable the suEXEC mechanism for the first time
 511     and an Apache server is already running you must kill and
 512     restart Apache. Restarting it with a simple HUP or USR1 signal
 513     will not be enough. <br />
 514      If you want to disable suEXEC you should kill and restart
 515     Apache after you have removed the "suexec" file. <br />
 516      <br />
 517
 518
 519     <p align="CENTER"><strong><a href="suexec.html">BACK TO
 520     CONTENTS</a></strong></p>
 521
 522     <h3><a id="usage" name="usage">Using suEXEC</a></h3>
 523
 524     <p align="LEFT"><strong>Virtual Hosts:</strong><br />
 525      One way to use the suEXEC wrapper is through the <a
 526     href="mod/mpm_common.html#user">User</a> and <a
 527     href="mod/mpm_common.html#group">Group</a> directives in <a
 528     href="mod/core.html#virtualhost">VirtualHost</a> definitions.
 529     By setting these directives to values different from the main
 530     server user ID, all requests for CGI resources will be executed
 531     as the <em>User</em> and <em>Group</em> defined for that
 532     <code>&lt;VirtualHost&gt;</code>. If only one or neither of
 533     these directives are specified for a
 534     <code>&lt;VirtualHost&gt;</code> then the main server userid is
 535     assumed.</p>
 536
 537     <p><strong>User directories:</strong><br />
 538      The suEXEC wrapper can also be used to execute CGI programs as
 539     the user to which the request is being directed. This is
 540     accomplished by using the "<strong><code>~</code></strong>"
 541     character prefixing the user ID for whom execution is desired.
 542     The only requirement needed for this feature to work is for CGI
 543     execution to be enabled for the user and that the script must
 544     meet the scrutiny of the <a href="#model">security checks</a>
 545     above.</p>
 546
 547     <p align="CENTER"><strong><a href="suexec.html">BACK TO
 548     CONTENTS</a></strong></p>
 549
 550     <h3><a id="debug" name="debug">Debugging suEXEC</a></h3>
 551
 552     <p align="LEFT">The suEXEC wrapper will write log information
 553     to the file defined with the --with-suexec-logfile option as
 554     indicated above. If you feel you have configured and installed
 555     the wrapper properly, have a look at this log and the error_log
 556     for the server to see where you may have gone astray.</p>
 557
 558     <p align="CENTER"><strong><a href="suexec.html">BACK TO
 559     CONTENTS</a></strong></p>
 560
 561     <h3><a id="jabberwock" name="jabberwock">Beware the Jabberwock:
 562     Warnings &amp; Examples</a></h3>
 563
 564     <p align="LEFT"><strong>NOTE!</strong> This section may not be
 565     complete. For the latest revision of this section of the
 566     documentation, see the Apache Group's <a
 567     href="http://www.apache.org/docs/suexec.html">Online
 568     Documentation</a> version.</p>
 569
 570     <p align="LEFT">There are a few points of interest regarding
 571     the wrapper that can cause limitations on server setup. Please
 572     review these before submitting any "bugs" regarding suEXEC.</p>
 573
 574     <ul>
 575       <li><strong>suEXEC Points Of Interest</strong></li>
 576
 577       <li>
 578         Hierarchy limitations
 579
 580         <blockquote>
 581           For security and efficiency reasons, all suexec requests
 582           must remain within either a top-level document root for
 583           virtual host requests, or one top-level personal document
 584           root for userdir requests. For example, if you have four
 585           VirtualHosts configured, you would need to structure all
 586           of your VHosts' document roots off of one main Apache
 587           document hierarchy to take advantage of suEXEC for
 588           VirtualHosts. (Example forthcoming.)
 589         </blockquote>
 590       </li>
 591
 592       <li>
 593         suEXEC's PATH environment variable
 594
 595         <blockquote>
 596           This can be a dangerous thing to change. Make certain
 597           every path you include in this define is a
 598           <strong>trusted</strong> directory. You don't want to
 599           open people up to having someone from across the world
 600           running a trojan horse on them.
 601         </blockquote>
 602       </li>
 603
 604       <li>
 605         Altering the suEXEC code
 606
 607         <blockquote>
 608           Again, this can cause <strong>Big Trouble</strong> if you
 609           try this without knowing what you are doing. Stay away
 610           from it if at all possible.
 611         </blockquote>
 612       </li>
 613     </ul>
 614
 615     <p align="CENTER"><strong><a href="suexec.html">BACK TO
 616     CONTENTS</a></strong></p>
 617     <!--#include virtual="footer.html" -->
 618   </body>
 619 </html>
 620