[Summary view] [Print] [Text view]

   1  @title Managing Daemons with phd
   2  @group config
   3  
   4  Explains Phabricator daemons and the daemon control program ##phd##.
   5  
   6  = Overview =
   7  
   8  Phabricator uses daemons (background processing scripts) to handle a number of
   9  tasks:
  10  
  11    - tracking repositories, discovering new commits, and importing and parsing
  12      commits;
  13    - sending email; and
  14    - collecting garbage, like old logs and caches.
  15  
  16  Daemons are started and stopped with **phd** (the **Ph**abricator **D**aemon
  17  launcher). Daemons can be monitored via a web console.
  18  
  19  You do not need to run daemons for most parts of Phabricator to work, but some
  20  features (principally, repository tracking with Diffusion) require them and
  21  several features will benefit in performance or stability if you configure
  22  daemons.
  23  
  24  = phd =
  25  
  26  **phd** is a command-line script (located at ##phabricator/bin/phd##). To get
  27  a list of commands, run ##phd help##:
  28  
  29    phabricator/ $ ./bin/phd help
  30    NAME
  31            phd - phabricator daemon launcher
  32    ...
  33  
  34  Generally, you will use:
  35  
  36    - **phd start** to launch all daemons;
  37    - **phd restart** to restart all daemons;
  38    - **phd status** to get a list of running daemons; and
  39    - **phd stop** to stop all daemons.
  40  
  41  If you want finer-grained control, you can use:
  42  
  43    - **phd launch** to launch individual daemons; and
  44    - **phd debug** to debug problems with daemons.
  45  
  46  NOTE: When you upgrade Phabricator or change configuration, you should restart
  47  the daemons by running `phd restart`.
  48  
  49  = Daemon Console =
  50  
  51  You can view status and debugging information for daemons in the Daemon Console
  52  via the web interface. Go to ##/daemon/## in your install or click
  53  **Daemon Console** from "More Stuff".
  54  
  55  The Daemon Console shows a list of all the daemons that have ever launched, and
  56  allows you to view log information for them. If you have issues with daemons,
  57  you may be able to find error information that will help you resolve the problem
  58  in the console.
  59  
  60  NOTE: The easiest way to figure out what's wrong with a daemon is usually to use
  61  **phd debug** to launch it instead of **phd start**. This will run it without
  62  daemonizing it, so you can see output in your console.
  63  
  64  = Available Daemons =
  65  
  66  You can get a list of launchable daemons with **phd list**:
  67  
  68    - **libphutil test daemons** are not generally useful unless you are
  69      developing daemon infrastructure or debugging a daemon problem;
  70    - **PhabricatorTaskmasterDaemon** performs work from a task queue;
  71    - **PhabricatorRepositoryPullLocalDaemon** daemons track repositories, for
  72      more information see @{article:Diffusion User Guide}; and
  73    - **PhabricatorGarbageCollectorDaemon** cleans up old logs and caches.
  74  
  75  = Debugging and Tuning =
  76  
  77  In most cases, **phd start** handles launching all the daemons you need.
  78  However, you may want to use more granular daemon controls to debug daemons,
  79  launch custom daemons, or launch special daemons like the IRC bot.
  80  
  81  To debug a daemon, use `phd debug`:
  82  
  83    phabricator/bin/ $ ./phd debug <daemon>
  84  
  85  You can pass arguments like this (normal arguments are passed to the daemon
  86  control mechanism, not to the daemon itself):
  87  
  88    phabricator/bin/ $ ./phd debug <daemon> -- --flavor apple
  89  
  90  In debug mode, daemons do not daemonize, and they print additional debugging
  91  output to the console. This should make it easier to debug problems. You can
  92  terminate the daemon with `^C`.
  93  
  94  To launch a nonstandard daemon, use `phd launch`:
  95  
  96    phabricator/bin/ $ ./phd launch <daemon>
  97  
  98  This daemon will daemonize and run normally.
  99  
 100  == General Tips ==
 101  
 102    - You can set the number of taskmasters that `phd start` starts by the config
 103      key `phd.start-taskmasters`. If you have a task backlog, try increasing it.
 104    - When you `phd launch` or `phd debug` a daemon, you can type any unique
 105      substring of its name, so `phd launch pull` will work correctly.
 106    - `phd stop` and `phd restart` stop **all** of the daemons on the machine, not
 107      just those started with `phd start`. If you're writing a restart script,
 108      have it launch any custom daemons explicitly after `phd restart`.
 109    - You can write your own daemons and manage them with `phd` by extending
 110      @{class:PhabricatorDaemon}. See @{article:libphutil Libraries User Guide}.
 111    - See @{article:Diffusion User Guide} for details about tuning the repository
 112      daemon.
 113  
 114  == Multiple Machines ==
 115  
 116  If you have multiple machines, you should use `phd launch` to tweak which
 117  daemons launch, and split daemons across machines like this:
 118  
 119    - `PhabricatorRepositoryPullLocalDaemon`: Run one copy on any machine.
 120      On each web frontend which is not running a normal copy, run a copy
 121      with the `--no-discovery` flag.
 122    - `PhabricatorGarbageCollectorDaemon`: Run one copy on any machine.
 123    - `PhabricatorTaskmasterDaemon`: Run as many copies as you need to keep
 124      tasks from backing up. You can run them all on one machine or split them
 125      across machines.
 126  
 127  A gratuitously wasteful install might have a dedicated daemon machine which
 128  runs `phd start` with a large pool of taskmasters set in the config, and then
 129  runs `phd launch PhabricatorRepositoryPullLocalDaemon -- --no-discovery` on each
 130  web server. This is grossly excessive in normal cases.
 131  
 132  = Next Steps =
 133  
 134  Continue by:
 135  
 136    - learning about the repository daemon with @{article:Diffusion User Guide};
 137      or
 138    - writing your own daemons with @{article:libphutil Libraries User Guide}.