bc-agent installation

Requirements

  • Unix operating system
  • Java 8
  • ssh
  • sudo

Installation

  1. download bc-agent distribution file

root# cd /downloads-directory
root# wget http://beyondcron.com/downloads/bc-agent_version_all.deb

root# cd /downloads-directory
root# wget http://beyondcron.com/downloads/bc-agent_version-0.noarch.rpm

user% cd /downloads-directory
user% wget http://beyondcron.com/downloads/bc-agent-version.zip

  1. if it does not already exist, create /etc/apt/sources.list.d/beyondcron.list

root# echo 'deb https://beyondcron.com/dists/stable /' > /etc/apt/sources.list.d/beyondcron.list

the package apt-transport-https is required in order to use an https source. If you are unable to install this package, change the source entry to deb http://beyondcron.com/dists/stable /.

  1. if it does not already exist, download the BeyondCron signing key /etc/apt/trusted.gpg.d/beyondcron.gpg

root# cd /etc/apt/trusted.gpg.d
root# wget https://beyondcron.com/dists/stable/beyondcron.gpg

  1. update package index files

root# apt-get update

  1. if it does not already exist, create /etc/yum/repos.d/beyondcron.repo

root# cat > /etc/yum.repos.d/beydoncron.repo << EOF
[beyondcron]
name=BeyondCron packages
baseurl=http://beyondcron.com/dists/stable
gpgcheck=1
gpgkey=http://beyondcron.com/dists/stable/RPM-GPG-KEY-beyondcron
metadata_expire=300
enabled=1
EOF

  1. install package and start daemon
  1. install package and start daemon

root# dpkg -i bc-agent_version_all.deb

root# rpm -i bc-agent_version-0.noarch.rpm

root# apt-get install bc-agent

root# yum install bc-agent

If they do not already exist, installing this package will create the following:

  • operating system user bc-daemon to run bc-agent;
  • directory /opt/bc-agent containing this package;
  • configuration file /etc/default/bc-agent;
  • log file /var/log/bc-agent.log on initd systems;

It will also register and start bc-agent as a service.

if the package cannot find a version of Java 8 already installed, the installation will fail.

Starting/stopping

On init systems, the bc-agent service can be started and stopped using the service command. e.g.

root# service bc-agent (start|stop)

On systemd systems, the bc-agent service can be started and stopped using the systemctl command. e.g.

root# systemctl (start|stop) bc-agent

Logging

On init systems, output is written to the file /var/log/bc-agent.log.

On systemd systems, output is written to the systemd journal and can be viewed using journalctl. e.g.

root# journalctl -u bc-agent

  1. move to the install directory

The distribution will will create the sub-directory bc-agent.

user% cd /install-directory

  1. unzip distribution

user% unzip /downloads-directory/bc-agent-version.zip

  1. confirm installation

user% ./bc-agent/bin/bc-agent --version

bc-agent version

Configuration variables

The following configuration variables can be defined within the file /etc/default/bc-agent.

BEYONDCRON_SERVER_NAMES one or more space separated server[:port]s to connect to. Default is the name returned by /bin/hostname.
BEYONDCRON_SERVER_PORT the server port number. Default is 5701.
BEYONDCRON_CLUSTER_NAME name of BeyondCron cluster to join. Default is beyondcron.
BEYONDCRON_CLUSTER_PASSWORD password of cluster. If password is in the format file:filename, then the password will be read from filename. Default is a cluster specific random string.
BEYONDCRON_AGENT_LOCAL start as a local job executor only.
BEYONDCRON_AGENT_USER_NAME name of user to connect to server as. Default is agent.
BEYONDCRON_AGENT_USER_PASSWORD password of user. If password is in the format file:filename, then the password will be read from filename. Default is a BeyondCron specific random string.
BEYONDCRON_HOST_NAME host name of agent. Default is the name returned by /bin/hostname.
BEYONDCRON_ALERT_COMMAND operating system command which is called when bc-agent stops unexpectedly. This can be used for example to send an email or SMS message. When called, the following environment variables will be set:
BEYONDCRON_ALERT_REASON – description of error. e.g. “bc-agent stopped unexpectedly” or “bc-agent stopped after receiving signal 15”.
BEYONDCRON_DAEMONbc-agent
BEYONDCRON_EXIT_CODE – exit code of bc-agent
BEYONDCRON_OS_USER – operating system user name which bc-agent was running under.
BEYONDCRON_ECHO enable/disable the echo command and url. Default is true, enabled.
BEYONDCRON_ECHO_HOST name of host whose commands/webhooks are sent to the echo command/url. Default is example.com.
BEYONDCRON_ECHO_COMMAND path to the echo command. Default is /opt/bc-agent/bin/echo.
BEYONDCRON_ECHO_URL URL to the echo url. Default is http://localhost:8080/echo.
BEYONDCRON_ENVIRONMENT_PATH value of PATH environment variable which is set when executing command jobs. Default = /usr/local/bin:/usr/bin:/bin
JAVA_OPTS one or more JVM options. e.g. -Xms2T -Xmx2M
JDBC_CLASSPATH location of one or more JDBC drivers, which are used when executing SQL jobs. BeyondCron includes drivers for MySQL and PostgreSQL databases.

if installing the BeyondCron components bc-agent, bc-server & bc-web on separate servers, then at least the variable BEYONDCRON_SERVER_NAMES will need to be set to include the names of each server.

Configure ssh

In order to execute commands on remote servers, bc-agent expects the bc-agent user to have passwordless ssh access to each remote server.

Configure sudo

When not running as root (the default configuration), bc-agent will attempt to execute jobs, locally and remotely, via sudo. As such you must allow the bc-agent user, default is bc-daemon, to execute commands for other users.

When not running as root (the default configuration), bc-agent will attempt to execute jobs, locally and remotely, via sudo. As such you must allow the bc-agent user, to execute commands for other users.

A minimal entry within the /etc/sudoers to allow the agent to execute commands for any user except root, would be:

username ALL=(ALL,!root) NOPASSWD:SETENV: ALL

If you wish to allow the BeyondCron agent to execute commands as root, the safest option is to explicitly define each command that you wish to allow the agent to execute. e.g.

username ALL=(ALL,!root) NOPASSWD:SETENV: ALL, (root) /usr/bin/tee,/sbin/reboot

BeyondCron uses the tee command so save the command output, so should always be included in the commands that the BeyondCron agent can sudo to.

if sudo is configured with a secure path, and you wish to allow BeyondCron/users to set the PATH environment variable, you can add the bc-agent user to the sudoers exempt_group. e.g.

Defaults exempt_group += bc-daemon

See also

Reference