init.md
1 Sample init scripts and service configuration for bitcoind 2 ========================================================== 3 4 Sample scripts and configuration files for systemd, Upstart and OpenRC 5 can be found in the contrib/init folder. 6 7 contrib/init/bitcoind.service: systemd service unit configuration 8 contrib/init/bitcoind.openrc: OpenRC compatible SysV style init script 9 contrib/init/bitcoind.openrcconf: OpenRC conf.d file 10 contrib/init/bitcoind.conf: Upstart service configuration file 11 contrib/init/bitcoind.init: CentOS compatible SysV style init script 12 13 Service User 14 --------------------------------- 15 16 All three Linux startup configurations assume the existence of a "bitcoin" user 17 and group. They must be created before attempting to use these scripts. 18 The macOS configuration assumes bitcoind will be set up for the current user. 19 20 Configuration 21 --------------------------------- 22 23 Running bitcoind as a daemon does not require any manual configuration. You may 24 set the `rpcauth` setting in the `bitcoin.conf` configuration file to override 25 the default behaviour of using a special cookie for authentication. 26 27 This password does not have to be remembered or typed as it is mostly used 28 as a fixed token that bitcoind and client programs read from the configuration 29 file, however it is recommended that a strong and secure password be used 30 as this password is security critical to securing the wallet should the 31 wallet be enabled. 32 33 If bitcoind is run with the "-server" flag (set by default), and no rpcpassword is set, 34 it will use a special cookie file for authentication. The cookie is generated with random 35 content when the daemon starts, and deleted when it exits. Read access to this file 36 controls who can access it through RPC. 37 38 By default the cookie is stored in the data directory, but its location can be 39 overridden with the option `-rpccookiefile`. Default file permissions for the 40 cookie are "owner" (i.e. user read/writeable) via default application-wide file 41 umask of `0077`, but these can be overridden with the `-rpccookieperms` option. 42 43 This allows for running bitcoind without having to do any manual configuration. 44 45 `conf`, `pid`, and `wallet` accept relative paths which are interpreted as 46 relative to the data directory. `wallet` *only* supports relative paths. 47 48 To generate an example configuration file that describes the configuration settings, 49 see [contrib/devtools/README.md](../contrib/devtools/README.md#gen-bitcoin-confsh). 50 51 Paths 52 --------------------------------- 53 54 ### Linux 55 56 All three configurations assume several paths that might need to be adjusted. 57 58 Binary: /usr/bin/bitcoind 59 Configuration file: /etc/bitcoin/bitcoin.conf 60 Data directory: /var/lib/bitcoind 61 PID file: /var/run/bitcoind/bitcoind.pid (OpenRC and Upstart) or 62 /run/bitcoind/bitcoind.pid (systemd) 63 Lock file: /var/lock/subsys/bitcoind (CentOS) 64 65 The PID directory (if applicable) and data directory should both be owned by the 66 bitcoin user and group. It is advised for security reasons to make the 67 configuration file and data directory only readable by the bitcoin user and 68 group. Access to bitcoin-cli and other bitcoind rpc clients can then be 69 controlled by group membership. 70 71 NOTE: When using the systemd .service file, the creation of the aforementioned 72 directories and the setting of their permissions is automatically handled by 73 systemd. Directories are given a permission of 710, giving the bitcoin group 74 access to files under it _if_ the files themselves give permission to the 75 bitcoin group to do so. This does not allow 76 for the listing of files under the directory. 77 78 NOTE: It is not currently possible to override `datadir` in 79 `/etc/bitcoin/bitcoin.conf` with the current systemd, OpenRC, and Upstart init 80 files out-of-the-box. This is because the command line options specified in the 81 init files take precedence over the configurations in 82 `/etc/bitcoin/bitcoin.conf`. However, some init systems have their own 83 configuration mechanisms that would allow for overriding the command line 84 options specified in the init files (e.g. setting `BITCOIND_DATADIR` for 85 OpenRC). 86 87 ### macOS 88 89 Binary: /usr/local/bin/bitcoind 90 Configuration file: ~/Library/Application Support/Bitcoin/bitcoin.conf 91 Data directory: ~/Library/Application Support/Bitcoin 92 Lock file: ~/Library/Application Support/Bitcoin/.lock 93 94 Installing Service Configuration 95 ----------------------------------- 96 97 ### systemd 98 99 Installing this .service file consists of just copying it to 100 /usr/lib/systemd/system directory, followed by the command 101 `systemctl daemon-reload` in order to update running systemd configuration. 102 103 To test, run `systemctl start bitcoind` and to enable for system startup run 104 `systemctl enable bitcoind` 105 106 NOTE: When installing for systemd in Debian/Ubuntu the .service file needs to be copied to the /lib/systemd/system directory instead. 107 108 ### OpenRC 109 110 Rename bitcoind.openrc to bitcoind and drop it in /etc/init.d. Double 111 check ownership and permissions and make it executable. Test it with 112 `/etc/init.d/bitcoind start` and configure it to run on startup with 113 `rc-update add bitcoind` 114 115 ### Upstart (for Debian/Ubuntu based distributions) 116 117 Upstart is the default init system for Debian/Ubuntu versions older than 15.04. If you are using version 15.04 or newer and haven't manually configured upstart you should follow the systemd instructions instead. 118 119 Drop bitcoind.conf in /etc/init. Test by running `service bitcoind start` 120 it will automatically start on reboot. 121 122 NOTE: This script is incompatible with CentOS 5 and Amazon Linux 2014 as they 123 use old versions of Upstart and do not supply the start-stop-daemon utility. 124 125 ### CentOS 126 127 Copy bitcoind.init to /etc/init.d/bitcoind. Test by running `service bitcoind start`. 128 129 Using this script, you can adjust the path and flags to the bitcoind program by 130 setting the BITCOIND and FLAGS environment variables in the file 131 /etc/sysconfig/bitcoind. You can also use the DAEMONOPTS environment variable here. 132 133 ### macOS 134 135 Copy org.bitcoin.bitcoind.plist into ~/Library/LaunchAgents. Load the launch agent by 136 running `launchctl load ~/Library/LaunchAgents/org.bitcoin.bitcoind.plist`. 137 138 This Launch Agent will cause bitcoind to start whenever the user logs in. 139 140 NOTE: This approach is intended for those wanting to run bitcoind as the current user. 141 You will need to modify org.bitcoin.bitcoind.plist if you intend to use it as a 142 Launch Daemon with a dedicated bitcoin user. 143 144 Auto-respawn 145 ----------------------------------- 146 147 Auto respawning is currently only configured for Upstart and systemd. 148 Reasonable defaults have been chosen but YMMV.