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

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