src/applications/config/option/PhabricatorAccessLogConfigOptions.php

   1 <?php
   2
   3 final class PhabricatorAccessLogConfigOptions
   4   extends PhabricatorApplicationConfigOptions {
   5
   6   public function getName() {
   7     return pht('Access Logs');
   8   }
   9
  10   public function getDescription() {
  11     return pht('Configure the access logs, which log HTTP/SSH requests.');
  12   }
  13
  14   public function getIcon() {
  15     return 'fa-list';
  16   }
  17
  18   public function getGroup() {
  19     return 'core';
  20   }
  21
  22   public function getOptions() {
  23     $common_map = array(
  24       'C' => pht('The controller or workflow which handled the request.'),
  25       'c' => pht('The HTTP response code or process exit code.'),
  26       'D' => pht('The request date.'),
  27       'e' => pht('Epoch timestamp.'),
  28       'h' => pht("The webserver's host name."),
  29       'p' => pht('The PID of the server process.'),
  30       'r' => pht('The remote IP.'),
  31       'T' => pht('The request duration, in microseconds.'),
  32       'U' => pht('The request path, or request target.'),
  33       'm' => pht('For conduit, the Conduit method which was invoked.'),
  34       'u' => pht('The logged-in username, if one is logged in.'),
  35       'P' => pht('The logged-in user PHID, if one is logged in.'),
  36       'i' => pht('Request input, in bytes.'),
  37       'o' => pht('Request output, in bytes.'),
  38       'I' => pht('Cluster instance name, if configured.'),
  39     );
  40
  41     $http_map = $common_map + array(
  42       'R' => pht('The HTTP referrer.'),
  43       'M' => pht('The HTTP method.'),
  44     );
  45
  46     $ssh_map = $common_map + array(
  47       's' => pht('The system user.'),
  48       'S' => pht('The system sudo user.'),
  49       'k' => pht('ID of the SSH key used to authenticate the request.'),
  50
  51       // TODO: This is a reasonable thing to support in the HTTP access
  52       // log, too.
  53       'Q' => pht('A random, unique string which identifies the request.'),
  54     );
  55
  56     $http_desc = pht(
  57       'Format for the HTTP access log. Use `%s` to set the path. '.
  58       'Available variables are:',
  59       'log.access.path');
  60     $http_desc .= "\n\n";
  61     $http_desc .= $this->renderMapHelp($http_map);
  62
  63     $ssh_desc = pht(
  64       'Format for the SSH access log. Use %s to set the path. '.
  65       'Available variables are:',
  66       'log.ssh.path');
  67     $ssh_desc .= "\n\n";
  68     $ssh_desc .= $this->renderMapHelp($ssh_map);
  69
  70     return array(
  71       $this->newOption('log.access.path', 'string', null)
  72         ->setLocked(true)
  73         ->setSummary(pht('Access log location.'))
  74         ->setDescription(
  75           pht(
  76             "To enable the HTTP access log, specify a path. This log is ".
  77             "more detailed than normal HTTP access logs (for instance, ".
  78             "it can show logged-in users, controllers, and other application ".
  79             "data).\n\n".
  80             "If not set, no log will be written."))
  81         ->addExample(
  82           null,
  83           pht('Disable access log.'))
  84         ->addExample(
  85           '/var/log/devtools/access.log',
  86           pht('Write access log here.')),
  87       $this->newOption(
  88         'log.access.format',
  89         // NOTE: This is 'wild' intead of 'string' so "\t" and such can be
  90         // specified.
  91         'wild',
  92         "[%D]\t%p\t%h\t%r\t%u\t%C\t%m\t%U\t%R\t%c\t%T")
  93         ->setLocked(true)
  94         ->setSummary(pht('Access log format.'))
  95         ->setDescription($http_desc),
  96       $this->newOption('log.ssh.path', 'string', null)
  97         ->setLocked(true)
  98         ->setSummary(pht('SSH log location.'))
  99         ->setDescription(
 100           pht(
 101             "To enable the SSH log, specify a path. This log can provide ".
 102             "more detailed information about SSH access than a normal SSH ".
 103             "log (for instance, it can show logged-in users, commands, and ".
 104             "other application data).\n\n".
 105             "If not set, no log will be written."))
 106         ->addExample(
 107           null,
 108           pht('Disable SSH log.'))
 109         ->addExample(
 110           '/var/log/devtools/ssh.log',
 111           pht('Write SSH log here.')),
 112       $this->newOption(
 113         'log.ssh.format',
 114         'wild',
 115         "[%D]\t%p\t%h\t%r\t%s\t%S\t%u\t%C\t%U\t%c\t%T\t%i\t%o")
 116         ->setLocked(true)
 117         ->setSummary(pht('SSH log format.'))
 118         ->setDescription($ssh_desc),
 119       $this->newOption('log.ssh-error.path', 'string', null)
 120         ->setLocked(true)
 121         ->setSummary(pht('SSH error log location.'))
 122         ->setDescription(
 123           pht(
 124             'To enable the SSH error log, specify a path. Errors occurring '.
 125             'in contexts where this software is serving SSH requests '.
 126             'will be written to this log.'.
 127             "\n\n".
 128             'If not set, no log will be written.'))
 129         ->addExample(null, pht('Disable SSH error log.'))
 130         ->addExample(
 131           '/var/log/devtools/ssh-error.log',
 132           pht('Write SSH error log here.')),
 133     );
 134   }
 135
 136   private function renderMapHelp(array $map) {
 137     $desc = '';
 138     foreach ($map as $key => $kdesc) {
 139       $desc .= "  - `%".$key."` ".$kdesc."\n";
 140     }
 141     $desc .= "\n";
 142     $desc .= pht(
 143       "If a variable isn't available (for example, %%m appears in the file ".
 144       "format but the request is not a Conduit request), it will be rendered ".
 145       "as '-'");
 146     $desc .= "\n\n";
 147     $desc .= pht(
 148       "Note that the default format is subject to change in the future, so ".
 149       "if you rely on the log's format, specify it explicitly.");
 150
 151     return $desc;
 152   }
 153
 154 }