Category: Agile

Linux Services

I have an Ubuntu Linux VM that runs Jenkins, and to make life simpler I wanted to set up Jenkins to run as a service. I also wanted it to start up automatically at boot time, as that’s the sole function of the VM it’s running on.

So, here are my notes on setting up Jenkins as a service on Ubuntu Linux, which includes a script to manage (start, stop, check, restart) the Jenkins process too.

On Ubuntu (and most othe rLinux versions) you can check the current services with the command “service –status-all” – this should give you a list of all services, and their current status. You can (as root) also do “service <name> start” (or stop or restart) for each one.

Jenkins as a Service

To create a new service for Jenkins, take a look at the existing scripts in /etc/init.d/ for some examples.

By convention there are three main methods a basic service implements, they are; start, stop and restart. About the most basic structure of a service script is therfore something like this:

#!/bin/bash start() { echo “Starting Service” # Do start things here. }stop() { echo “Stopping Service” # Do stop things here. }restart() { echo “Restarting Service…” stop start } case “$1″ in start) start ;; stop) stop ;; restart) restart ;; *)

obviously you still need to implement the start and stop functions though 🙂

To see a far more detailed example, take a look at the file /etc/init.d/skeleton, which you could copy and update to suit your needs if you prefer.

I decided on something halfway between the very basic example above and the far more complex example in “skeleton”, and did something like this (saved as “/etc/init.d/jenkins”):

# Example Jenkins auto-start service script # # description: manages Jenkins as a service # processname: jenkins # pidfile: /var/run/jenkins.pid # author: www.DonaldSimpson.co.uk# The user and the home dir that Jenkins runs under jenkins=/usr/local/jenkins # Your startup and stop scripts (see below) startup=$jenkins/bin/startup.sh shutdwn=$jenkins/bin/shutdown.shstart_jenkins() { echo “Starting Jenkins services…” su – jenkins -c “sh $startup” } stop_jenkins() { echo “Stopping Jenkins services…” su – jenkins -c “sh $shutdwn” } status_jenkins() { # Check for any other process containing jenkins.war # This could be improved upon (see script below) numproc=`ps -ef | grep [j]enkins.war | wc -l` if [ $numproc -ne 0 ]; then echo “Jenkins is running…” else echo “Jenkins is NOT running…” fi } case “$1” in start) start_jenkins ;; stop) stop_jenkins ;; status) status_jenkins ;; restart) stop_jenkins start_jenkins ;; *) echo “Usage: $0 {start|stop|status|restart}” exit 1 esac exit 0

Update that to suit then save and change the permissions to make it executable:

chmod +x /etc/init.d/jenkins

then you can check (as root) that you can call the methods in the script:

service jenkins status service jenkins stop service jenkins start

These should all now run as the Jenkins user via sudo and say something when called, even if it is just “I can’t find the scripts you told me to call” 🙂

Jenkins Startup and Stop scripts

So, you now need to create the missing startup and shutdown scripts, in my example they were:

/usr/local/jenkins/bin/startup.sh

and

/usr/local/jenkins/bin/shutdown.sh

An example of the Jenkins start-up and management script I normally use is at the end of this post – the main idea though, is that it sets what you want to set then starts Jenkins via nohup and outputs to a log file

I have also added and included some basic tests to my scripts and some (very) rudimentary error handling/checking, but you shoudl get the idea and all you really need is this line (with the variables set correctly):

${NOHUP} ${JAVA} -jar ${JENKINS_WAR} -D${MARKER} –httpListenAddress=0.0.0.0 –httpPort=${HTTP_PORT} > ${LOG_FILE} &

Note: I often run multiple instances of Jenkins, so I explicitly specify the HTTP_PORT, and I use the -D${MARKER} to allow me to safely and easily find the correct PID for each project.
The httpListenAddress can normally go unset, but it’s something I’ve had to set before on multi-home’d hosts.

The stop part of my Jenkins management script finds the correct PID like this (and you could use a filter for the correct -D${MARKER} if you want that too):

PID=`${LSOF} -w -n -i tcp:${HTTP_PORT} | ${GREP} -v COMMAND | ${AWK} {‘print $2’}`

and simply kills it.

For some of my scripts I also filter for process ID’s that were started in the current directory by checking “pwdx” against the PID, but only where I’m sure the corresponding start-up process is correct/reliable.

So, tweak to your taste and that should be the Jenkins service created and working too now; for start|stop|restart you can create individual scripts or wrappers that call something like the one script below with parameters, or break the script in to separate files if you prefer.

Setting Jenkins to start at boot time

If you want to start Jenkins at boot time/startup automatically then you still need to do one more small step.  There are many different ways to do this depending on personal preference, your requirements and your version of Linux, but on Ubuntu it can be done easily with:

update-rc.d jenkins defaults

“update-rc.d” simply installs and removes System-V style init script links – read the man page for full details, but the same idea applies to most versions of Linux.

update-rc.d -f  jenkins remove

will undo this if you no longer want it.

An example Jenkins server/process management script

As an example, here is my script to manage Jenkins processes – it could use some improvements but the basic start, stop, restart and check should give you enough to sort out something that works and suits your needs.

Better formatted version available here: https://github.com/DonaldSimpson/scripts/blob/master/JenkinsProcessManager.sh

#! /bin/bash -p # www.donaldsimpson.co.uk # Script to start|stop|restart|check an instance of Jenkins # For each new instance, the PROJECT and HTTP_PORT need to be updated: export PROJECT=jenkins export HTTP_PORT=9000 EXIT_STRING=”” JENKINS_ROOT=/opt/apps/jenkins export JENKINS_HOME=${JENKINS_ROOT}/${PROJECT} JENKINS_WAR=${JENKINS_HOME}/jenkins.warWAIT_TIME=5 START_WAIT_TIME=15 JAVA_HOME=/usr PATH=$JAVA_HOME/bin:$PATH JAVA=${JAVA_HOME}/bin/java NOHUP=/usr/bin/nohup LOG_FILE=${JENKINS_HOME}/debug_${PROJECT}.log MARKER=”JenkinsProcFor_${PROJECT}”NC=/bin/nc WGET=/usr/bin/wget LSOF=/usr/bin/lsof AWK=/usr/bin/awk GREP=/bin/grep FUSER=/bin/fuser ################################################################################# ### Functions Start ############################################################# ################################################################################# cleanup(){ # Perform any clean-up activities here… [ “${EXIT_STRING}” != “0” ] && echo `date “+%d/%m/%y %H:%M:%S”` ${EXIT_STRING} exit 0 } trap ” QUIT _error() { EXIT_STRING=”${1}” [ “${1}” != “0” ] && EXIT_STRING=”ERROR: ${1}, please investigate, terminating.” cleanup  # Never returns from this call… } say(){ echo `date “+%d/%m/%y %H:%M:%S”` “${1}” } saybold(){ tput bold 2>/dev/null echo `date “+%d/%m/%y %H:%M:%S”` “${1}” tput sgr0 2>/dev/null } check_folders(){ say “” saybold “Checking all required folders exist…” for REQUIRED_DIR in ${JENKINS_ROOT} ${JENKINS_HOME} ${JAVA_HOME} do [ ! -d “${REQUIRED_DIR}” ] && _error “Necessary directory: ${REQUIRED_DIR} does not exist” say “Found required directory: ${REQUIRED_DIR}” done saybold “Done.” say “” } check_files(){ say “” saybold “Checking all required files exist…” for REQUIRED_FILE in ${JENKINS_WAR} ${NC} ${WGET} ${JAVA} ${LSOF} ${FUSER} ${GREP} ${AWK} do [ ! -f “${REQUIRED_FILE}” ] && _error “Necessary file: ${REQUIRED_file} does not exist” say “Found required file ${REQUIRED_FILE}” done saybold “Done.” say “” } check_port_closed(){ say “Checking that port ${HTTP_PORT} is closed…” ${NC} -w 1 localhost ${HTTP_PORT} if [ $? -eq 0 ]; then _error “Required Jenkins port ${HTTP_PORT} is already in use” else say “Ok, required port ${HTTP_PORT} is available, continuing…” fi } check_port_open(){ say “Checking that port ${HTTP_PORT} is open…” ${NC} -w 1 localhost ${HTTP_PORT} if [ $? -eq 0 ]; then say “Ok, a process is listening on port ${HTTP_PORT}, continuing…” else _error “Required Jenkins port ${HTTP_PORT} has not been opened.” fi } start_process(){ cd ${JENKINS_HOME} saybold “Starting Process now…” ${NOHUP} ${JAVA} -jar ${JENKINS_WAR} -D${MARKER} –httpListenAddress=0.0.0.0 –httpPort=${HTTP_PORT} > ${LOG_FILE} & say “Process initiated.” } check_log(){ say “Checking the log file ${LOG_FILE} for an HTTP listener…” STARTED=`${GREP} -c “HTTP Listener started” ${LOG_FILE}` if [ ${STARTED} -eq “0” ]; then _error “An HTTP Listener has not reported as started in the log file ${LOG_FILE}” else saybold “An HTTP Listener is reported as started in the log file ${LOG_FILE}” fi } check_html(){ # These checks need error handling, but you get the general idea. say “Checking that localhost:${HTTP_PORT} is serving Jenkins pages…” TEMP_WGETDIR=tempwgetdir$$ mkdir ${TEMP_WGETDIR} cd ${TEMP_WGETDIR} ${WGET} -q http://localhost:${HTTP_PORT} GOT_HTML=`${GREP} -c Dashboard index.html` cd ${JENKINS_HOME} rm -rf ${TEMP_WGETDIR} if [ ${GOT_HTML} -eq “0” ]; then _error “Unable to get an HTML page from the Server.” fi saybold “Recieved valid HTML from the server, all looks ok.” } check_process(){ check_port_open check_log check_html say “A Jenkins instance is listening on port ${HTTP_PORT} for project ${PROJECT}.” say “The process is logging debug info to the log file: ${LOG_FILE}” } stop_proc(){ check_port_open saybold “Looking for the Process ID attached to port ${HTTP_PORT}” PID=`${LSOF} -w -n -i tcp:${HTTP_PORT} | ${GREP} -v COMMAND | ${AWK} {‘print $2’}` if [ “${PID}” == “” ]; then saybold “Unable to detect the Process ID that is listening on port ${HTTP_PORT}!” PID=`${FUSER} ${LOG_FILE}` if [ “${PID}” == “” ]; then _error “Unable to find the PID that has the log file open too!” else say “Ok, found PID ${PID}” fi else saybold “Found a PID of $PID, killing it now…” fi kill -9 ${PID} say “Waiting ${WAIT_TIME} seconds for the process to die…” sleep ${WAIT_TIME} saybold “Done, checking port is closed…” check_port_closed saybold “All done.” } start(){ check_folders check_files check_port_closed start_process saybold “Waiting ${START_WAIT_TIME} seconds for the process to start up…” sleep ${START_WAIT_TIME} check_process } restart(){ stop_proc start } ################################################################################# ### Script Start ################################################################ ################################################################################# case “$1” in start) start ;; stop) stop_proc ;; restart) restart ;; check) check_process ;; *) echo “Usage: $0 {start|stop|restart|check}” esac # Exit cleanly _error “0”

Hope that helps! Any constructive comments, requests or suggestions for improvement are very welcome 🙂

Cheers, and sorry about the indenting,

Don

This Jenkins Agent Nodes post covers:

• What are they?
• Why may I want one?
• How do you create one?
  • tasks on On the Master/Server
  • tasks on On the Agent/Client
• Other ways of creating Agent Nodes
• Related posts and links

What are they?

Jenkins Agents  are small Java “Client” processes that connect back to a “Master” Jenkins instance over the Java Network Launch Protocol (JNLP).

Why may I want one?

Once it’s up and running, an Agent instance can be used to run tasks from a Master Jenkins instance on one or more remote machines providing an easy to use and flexible distributed system which can lend itself to a wide variety of tasks.

As these are Java processes, you are not restricted by architecture and can mix and match the OS’s of your agent nodes as required – Windows, Linux, UNIX, iSeries, OVMS etc – anything capable of running a modern version of Java (I think JNLP was introduced in 1.5?) and you can also group and categorize subsets of different types (both logical and physical) of Agents; intended use, availability, location, available resources, Cloud or VM versus Physical tin – anything that helps you decide when you want to use which host.

There are many different ways you can choose to utilize these nodes – they can be used to spread the load of an intensive build process over many machines when they are available, you can delegate specific tasks to specific machines only, or you can use labels to group different classes or types of Nodes that are available for certain tasks, making the most use of your available resources. You can also have Jenkins create Cloud server instances – Amazon EC2 for example – when certain thresholds are reached, and stop them when they are no longer required.

This post focuses on a pretty manual approach to the creation of Jenkins Agent Nodes with the intention of explaining them well enough to allow you to create them on any platform that can run a modern version of Java – there are probably simpler solutions depending on your needs and setup. A later post will touch on a few of the many possible uses for these nodes.

So, how do you create one?

There are several different ways to go about setting up an Agent, and the “best” approach depends on your situation, needs and environment(s) – for a simple Linux setup letting Jenkins do all the work for you makes life really easy, you can just select that option in your new Jenkins Agent Node and complete this screen to have Jenkins set it up for you:

Where the Username and Password are the credentials you want Jenkins to use to connect and start the Agent process on the remote server. This simple approach also allows the Master instance to initiate the JNLP connection and bring your agents online when required, avoiding any need to manually visit each agent node.

This keeps things nice and simple and reduces the admin overhead too,  but sometimes this type of approach can’t be used (on different OS’s like OVMS, iSeries, Windows etc) and I’m going to go on to outline what I think is the most “versatile” method – defining the Node on the Master instance, and manually setting up and starting the corresponding Agent/Client Node on the remote host – going through these steps should provide enough detail on how Agent Nodes work and connect to get one up and running on anything that can run a JVM.

1. On the Master/Server

Define the host: navigate to Jenkins > Manage Jenkins > Manage Nodes > New Node
Enter a suitable Node Name (I’d recommend something descriptive, and usually including the host name or part of it) then either select to create a “Dumb Agent” or copy an existing Node if you have one, then complete the configuration page similar to this:

where you specify the requested properties – path, labels, usage, executors etc. These are explained in more detail in the “?” for each item if required.

Here you can also state if you want to keep your Jenkins Agent for tied jobs only, or if it is to be utilized as much as possible – this obviously depends on your requirements. You can also specify the Launch method that best applies to your needs & requirements.

2. On the Agent/Client host

You don’t need to do very much to create a new agent node – typically if I’m setting up a few *NIX and Windows hosts I would archive a simple shell/DOS script that starts and manages the process along with the slave.jar file from the Master Jenkins instance. There are alternative methods that may suit your needs – you can start agents via SSH from the Master server for example and there’s a comparable method for Windows – but this simple approach should help you understand the underlying idea that applies to them all.

You can “wget” (or use a Browser on Windows) the slave.jar file directly from the Master Jenkins instance using the URL

http://[your jenkins host]:[port number]/jnlpJars/slave.jar

If you let JNLP initiate the process, the slave.jar will be downloaded from Jenkins automatically.

Note that Jenkins will inherit the effective permissions of the user that starts the process – this is to be expected, but it’s often worth having a think about the security aspects of this, along with the access requirements for the types of things you want your agent to be able to do… or not do.

On Windows hosts, you can use the jenkins-agent.exe to easily install Jenkins as a Windows Service, which can then be started at boot time and run under whatever user/permissions you wish set via the Services panel.

My *NIX “startagent.sh” script does a few environment/sanity checks, then kicks of the agent process something like so:

${NOHUP} ${JAVA} -jar slave.jar -jnlpUrl http://SERVERNAME:PORT/computer/USER__NODENAME/slave-agent.jnlp &

The HTTP URL there should match the one provided by the Jenkins page when you were defining the Node. If all goes well you should see the node state changed to Connected on the Master Hudson instance, and if not, then nohup.out should provide some pretty obvious pointers on the problem.

Some common causes are:

Jenkins host, port or node name wrong
Java version not found/wrong
Lack of write permissions to the file system
Lack of space (check /tmp too)
Port already in use
Errors in the jenkins-slave.xml file if you’ve tweaked it
Firewalls…

Jenkins also provides some health monitoring of the connected Node which you can see in the Jenkins > Nodes page:
Disk Space, Free Temp Space, Clock time/sync, Response Time and Free Swap are monitored
and you can have your Node taken off line if any of these passes a set threshold.

This should hopefully be enough info to provide an overview of what Jenkins Agents are, and enough to get one up and running on your chosen platform. Where possible it’s best to keep things simple – use SSH and let the Master instance manage things for you if you can – but when that’s not possible there are alternatives.

When I get the chance I will add some information on the next steps – creating and delegating jobs on Jenkins Agent Nodes, and some thoughts and suggestions for just a few of the many uses for this sort of distributed Build and Deployment system.

Related Posts and Links:

Monitoring Jenkins Slave Nodes with Groovy
– how to keep an  eye on your Jenkins Slaves

Jenkins Slave Nodes – using the Swarm Plugin
– automatically connect new Slave Nodes to create a “Swarm”

Getting the current user in Jenkins
– several approaches

Managing Jenkins as a service and starting at boot time
– on Linux & Windows

Jenkins plugins
– details on some of my most frequently used plugins

Jenkins DIY Information Radiators
– what they are for, and how to make your own

The Jenkins Wiki has more details information on Distributed Builds and different slave-launching strategies.

Feedback, questions and constructive comments are very welcome!