Starting Jenkins
The easiest way to execute Jenkins is through the built in Jetty servlet container. You can execute Jenkins like this:
$ java -jar jenkins.war
Of course, you probably want to send the output of Jenkins to a log file, and if you're on Unix, you probably want to use nohup
:
$ nohup java -jar jenkins.war > $LOGFILE 2>&1
Accessing Jenkins
To see Jenkins, simply bring up a web browser and go to URL http
://
myServer
:8080
where myServer is the name of the system running Jenkins.
Command Line Parameters
Jenkins normally starts up using port 8080. However, if you have other web services starting up you might find that this port is already taken. You can specify a different port by using --httpPort=
$HTTP_PORT
where $HTTP_PORT
is the port you want Jenkins to run on. Other command line parameters include:
Command Line Parameter | Description |
---|---|
--help | Displays all available options and their usage |
--httpPort=$HTTP_PORT | Runs Jenkins listener on port $HTTP_PORT using standard http protocol. The default is port 8080. To disable (because you're using https), use port |
--httpListenAddress=$HTTP_HOST | Binds Jenkins to the IP address represented by $HTTP_HOST. The default is 0.0.0.0 — i.e. listening on all available interfaces. |
--httpsPort=$HTTPS_PORT | Uses HTTPS protocol on port $HTTPS_PORT. This option does not impact the root URL being generated within Jenkins logic (UI, JNLP files, etc.); it is defined by the Jenkins URL specified in the global configuration. |
--httpsListenAddress=$HTTPS_HOST | Binds Jenkins to listen for HTTPS requests on the IP address represented by $HTTPS_HOST. |
--http2Port=$HTTP_PORT | Uses HTTP/2 protocol on port $HTTP_PORT. This option does not impact the root URL being generated within Jenkins logic (UI, JNLP files, etc.); it is defined by the Jenkins URL specified in the global configuration. |
--http2ListenAddress=$HTTPS_HOST | Binds Jenkins to listen for HTTP/2 requests on the IP address represented by $HTTPS_HOST. |
--prefix=$PREFIX | Runs Jenkins to include the $PREFIX at the end of the URL. |
--ajp13Port=$AJP_PORT | Runs Jenkins listener on port $AJP_PORT using standard AJP13 protocol. The default is port 8009. To disable (because you're using https), use port |
--ajp13ListenAddress=$AJP_HOST | Binds Jenkins to the IP address represented by $AJP_HOST. The default is 0.0.0.0 — i.e. listening on all available interfaces. |
--argumentsRealm.passwd.$ADMIN_USER | Sets the password for user $ADMIN_USER. If Jenkins security is turned on, you must log in as the $ADMIN_USER in order to configure Jenkins or a Jenkins project. NOTE: You must also specify that this user has an admin role. (See next argument below). |
--argumentsRealm.roles.$ADMIN_USER=admin | Sets that $ADMIN_USER is an administrative user and can configure Jenkins if Jenkins' security is turned on. See Securing Jenkins for more information. |
--sessionTimeout=$SESSION_TIMEOUT | Sets the http session timeout value to $SESSION_TIMEOUT minutes. Default to what webapp specifies, and then to 60 minutes |
--useJmx | Enable Jetty JMX (See documentation) |
-Xdebug -Xrunjdwp:transport=dt_socket,address=$DEBUG_PORT,server=y,suspend=n | Sets debugging on and you can access debug on $DEBUG_PORT. |
--logfile=$LOG_PATH/winstone_`date +"%Y-%m-%d_%H-%M"`.log | Logging to desired file |
-XX:PermSize=512M -XX:MaxPermSize=2048M -Xmn128M -Xms1024M -Xmx2048M | referring to these options for Oracle Java |
Jenkins passes all (or just leading parameters until the first Jenkins-specific parameter?) command line parameters to the Winstone servlet container, so you can get more information by looking at the Winstone Command Line Parameter Reference and jenkinsci/winstone.
Be Careful with Command Line Parameters
Jenkins ignores command line parameters it doesn't understand instead of producing an error. Be careful when using command line parameters and make sure you have the correct spelling. For example, the parameter needed for defining the Jenkins administrative user is --argument
s
Realm
and not --argumentRealm
.
A very simple init script
The following script is for Ubuntu based systems. The RedHat Jenkins distribution contains a startup script.
#!/bin/sh DESC="Jenkins CI Server" NAME=jenkins PIDFILE=/var/run/$NAME.pid RUN_AS=jenkins COMMAND="/usr/bin/java -- -jar /home/jenkins/jenkins.war" d_start() { start-stop-daemon --start --quiet --background --make-pidfile --pidfile $PIDFILE --chuid $RUN_AS --exec $COMMAND } d_stop() { start-stop-daemon --stop --quiet --pidfile $PIDFILE if [ -e $PIDFILE ] then rm $PIDFILE fi } case $1 in start) echo -n "Starting $DESC: $NAME" d_start echo "." ;; stop) echo -n "Stopping $DESC: $NAME" d_stop echo "." ;; restart) echo -n "Restarting $DESC: $NAME" d_stop sleep 1 d_start echo "." ;; *) echo "usage: $NAME {start|stop|restart}" exit 1 ;; esac exit 0
Using HTTPS with an existing certificate
If you're setting up Jenkins using the built-in Winstone server and want to use an existing certificate for HTTPS:
--httpPort=-1 --httpsPort=443 --httpsKeyStore=path/to/keystore --httpsKeyStorePassword=keystorePassword
The keystore should be in JKS format (as created by the JDK 'keytool') and the keystore and target key must have the same password. (Placing the keystore arguments after Jenkins-specific parameters does not seem to work; either they are not forwarded to Winstone or Winstone ignores them coming after unknown parameters. So, make sure they are adjacent to the working --httpsPort
argument.)
If your keystore contains multiple certificates (e.g. you are using CA signed certificate) Jenkins might end-up using a incorrect one. In this case you can convert the keystore to PEM and use following command line options:
--httpPort=-1 --httpsPort=443 --httpsCertificate=path/to/cert --httpsPrivateKey=path/to/privatekey
Passing the Command Line Parameters to an instance on a Mac OSX (Currently is Mavericks 10.9.4) that uses launchctl (rather than using Jenkins.jar to start up)
In this example, we set the Jenkins server to listen for HTTPS on port 8443. Note that we do not disable the httpPort by passing in -1. So in this example, your server would answer on both http and https. We also assume that the user has already created the keystore (see the "Using SSL" section from http://wiki.wocommunity.org/display/documentation/Installing+and+Configuring+Jenkins)
sudo launchctl unload /Library/LaunchDaemons/org.jenkins-ci.plist sudo defaults write /Library/Preferences/org.jenkins-ci httpsPort 8443 sudo defaults write /Library/Preferences/org.jenkins-ci httpsKeyStore /path/to/your/keystore/file sudo defaults write /Library/Preferences/org.jenkins-ci httpsKeyStorePassword <keystore password> sudo launchctl load /Library/LaunchDaemons/org.jenkins-ci.plist
Using HTTP/2
With Java 8 (should be included per default in Java 9), you need to include alpn boot jar in the bootclasspath. The alpn boot jar depends on your jvm version. Have a look here https://www.eclipse.org/jetty/documentation/current/alpn-chapter.html#alpn-versions to figure which version to use.
You can download it from (with alpn boot version 8.1.12.v20180117): https://repo.maven.apache.org/maven2/org/mortbay/jetty/alpn/alpn-boot/8.1.12.v20180117/alpn-boot-8.1.12.v20180117.jar
Then you have to include it on jvm start:
java -Xbootclasspath/p:alpn-boot-8.1.12.v20180117.jar -jar target/jenkins.war --http2Port=9090
Configuring https certificates with Windows
Creating a certificate for use within Jenkins. This used a stock Jenkins 1.612 installation on Windows Server 2008 R2 Standard 64-bit. This creates a certificate signed by a Certificate Authority such as Digicert, if making your own certificate skip steps 3, 4, and 5.
This process utilizes Java's keytool, however you do not have to perform a separate Java installation if you don't need it. Jenkins packages a JRE with it when you do the installation, located in C:\Program Files (x86)\Jenkins\jre\bin
Step 1: Create a new keystore on your server. This will place a 'keystore' file in your current directory.
C:\Program Files (x86)\Jenkins\jre\bin>keytool -genkeypair -keysize 2048 -keyalg RSA -alias jenkins -keystore keystore Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: server-name.your.company.com What is the name of your organizational unit? [Unknown]: Your City What is the name of your organization? [Unknown]: Your company name What is the name of your City or Locality? [Unknown]: Your city What is the name of your State or Province? [Unknown]: Your State What is the two-letter country code for this unit? [Unknown]: US Is CN=server-name.your.company.com, OU=Your City, O=Your company name, L=Your City, ST=Your State, C=US correct? [no]: yes Enter key password for <jenkins> (RETURN if same as keystore password):
Step 2: Verify the keystore was created (your fingerprint will vary)
C:\Program Files (x86)\Jenkins\jre\bin>keytool -list -keystore keystore Enter keystore password: Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry jenkins, May 6, 2015, PrivateKeyEntry, Certificate fingerprint (SHA1): AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA
Step 3: Create the certificate request. This will create a 'certreq.csr' file in your current directory.
C:\Program Files (x86)\Jenkins\jre\bin>keytool -certreq -alias jenkins -keyalg RSA -file certreq.csr -ext SAN=dns:server-name,dns:server-name.your.company.com -keystore keystore Enter keystore password:
Step 4: Use the contents of the certreq.csr
file to generate a certificate from your certificate provider. Request a SHA-1 certificate (SHA-2 is untested but will likely work). If using DigiCert, download the resulting certificate as Other format "a .p7b bundle of all the certs in a .p7b file".
Step 5: Add the resulting .p7b into the keystore you created above.
C:\Program Files (x86)\Jenkins\jre\bin>keytool -import -alias jenkins -trustcacerts -file response_from_digicert.p7b -keystore keystore Enter keystore password: Certificate reply was installed in keystore
Step 6: Copy the 'keystore' file to your Jenkins secrets directory. On a stock installation, this will be at
C:\Program Files (x86)\Jenkins\secrets
Step 7: Modify the <arguments> section of your C:\Program Files (x86)\Jenkins\jenkins.xml
file to reflect the new certificate. Note: This example disables http via --httpPort=-1
and places the server on 8443
via --httpsPort=8443
.
<arguments>-Xrs -Xmx256m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar "%BASE%\jenkins.war" --httpPort=-1 --httpsPort=8443 --httpsKeyStore="%BASE%\secrets\keystore" --httpsKeyStorePassword=your.password.here</arguments>
Step 8: Restart the jenkins service to initialize the new configuration.
net stop jenkins net start jenkins
Step 9: After 30-60 seconds, Jenkins will have completed the startup process and you should be able to access the website at https://server-name.your.company.com:8443; Verify the certificate looks good via your browser's tools. If the service terminates immediately, there's an error somewhere in your configuration. Useful error information can be found in:
C:\Program Files (x86)\Jenkins\jenkins.err.log C:\Program Files (x86)\Jenkins\jenkins.out.log
16 Comments
Unknown User (kesten)
The >java -jar jenkins.war works fine in my ubuntu terminal. It says it's running.
But pointing my browser to se it? I know the port it's on because the terminal output tells me.
But what is my server name? I thought using the .war i don't need a server like apache.
[Winstone 2011/11/12 21:10:51] - Container startup failed
java.io.IOException: Failed to start a listener: winstone.HttpListener
errors.......
Caused by: java.net.BindException: Address already in use
so i guess the question is, how to find an open port?
.... ok, so it looks like if you suggest port 0, computer will search for an open one.
so now i use
java -jar jenkins.war
--httpPort=0
winstone starts running... yay! But eventually there is this error:
INFO: Accepted connection #1 from /127.0.0.1:51728
Nov 12, 2011 9:35:51 PM hudson.TcpSlaveAgentListener$ConnectionHandler run
WARNING: Connection #1 failed
java.io.EOFException
and i'm still not clear on what should go in the address bar when using the winstone servlet
kesten
Unknown User (kesten)
SOLVED
The failed connection was likely due to poor internet connectivity.
I was able to get the Jenkins dashboard in my browser by pointing it to address 127.0.0.1:8080
following a tutorial. http://equis.cs.queensu.ca/wiki/index.php/Running_Web_Applications_in_Eclipse
Unknown User (joelbdoin)
Is there a switch that can be passed to Jenkins on startup that will disable email ... or a configuration setting?
Unknown User (joelbdoin)
Found an alternative. I used the Configuration Slicing Plugin. This is either installed by default or I had already installed it, because it was available as an option from my Manage Jenkins page. I simply used the E-mail Notification slicer and cleared out the settings for all of my jobs, saving things (screen grab) for a later restore.
I thought I had seen an option for starting Hudson/Jenkins, via the default Winstone container, that toggled email on/off. After doing a bit more searching, I suspect that it was a tomcat-hosted Hudson/Jenkins that I had been using with --disable-email-something-or-other.
Unknown User (highflyer)
Hello,
I have just started with Jenkins and it is great - if it starts. I have a very big problem and cannot find any information on this page or in Google on how to solve it. I downloaded and installed the Windows package latest version 1.457 and I have installed it as a Windows Service for use with the shipped Winstone servlet container. My system is a Windows XP SP3 system with .Net 3.5, Java in version 1.7, and I am admin on the system.
After installation the Jenkins service is correctly started and it works. But if I stop the service, a restart is most of the times impossible, but in very rare cases it works. In the failure cases all I get is the error message that the service Jenkins was started on Local Computer and then halted. The event log does not give any hint, even the log files in the Jenkins program folder do not inform me. How can I enable the Java logging to find the reason for the startup problem? The examples on the page refer to logging of disk space, but sorry, I am not a Java programmer I do not know on how to enable other loggings (I want to use Jenkins for queuing of time-consuming report jobs). Can anybody help me saying which switch I have to set to enable this logging?
And what is very weird: If I start the service with "java -jar jenkins.war" all the configuration that I did, when I started it as a service, is gone - like a totally new installation. And if for some reason I get the Windows service started, the original configuration with all jobs is back. So there must be a difference in the service and in the manual start as a java program. Would it be possible to specify the configuration that I configured while it was started as a service, with "java -jar jenkins.war"?
Sorry, maybe it is all trivial, because I seem to be the only one with these questions, but however I do not find it myself and would appreciate any support.
Steve
Unknown User (garg)
When I run
$ java -jar jenkins.war on Windows XP
it creates .jenkins/workspace under user.home see below:
Running from: C:\Jenkins\jenkins.war
webroot: $user.home/.jenkins
Is it possible assign to another directory for instance: C:\web\.jenkins ?
Could you suggest me please?
Unknown User (what_a_fool)
Hi. In case you haven't found a solution yet, here's what I think should work (at least it seems to work with version 1.537 on Windows 7). Set your JENKINS_HOME environment variable to the desired path (i.e. C:\web\.jenkins, in your case). Then restart your jenkins.war (be sure to do it in the same Shell window in which you've set the JENKINS_HOME environment variable).
If you're running Jenkins as a Windows service, also edit jenkins.xml (located in the Jenkins install directory) and comment out the line <env name="JENKINS_HOME" value="%BASE%"/>, or else Jenkins will ignore your JENKINS_HOME environment variable. Hope this helps.
Unknown User (davida2009)
May I suggest documenting the --sessionTimeout parameter (introduced in 1.528) here?
Unknown User (he1)
I am having trouble running jenkins in https. I have a certificate (.CER) and I generated the jks file and used the same password. the server would not start.
Unknown User (inebrious)
many of the config elements on the winstone site are no longer valid. Any chance that could be updated here?
Unknown User (dhs)
Errh, do we really need to expose the keystore PASSWORD on the command line, where everyone with access to the server can read it by simply running ps? Shouldn't that be placed into some config file, which can at least be protected by file system permissions?
Unknown User (jochen_hayek)
Look into the "--httpsPrivateKey=…" command line option, that may serve your purpose.
Unknown User (jochen_hayek)
Why does --logfile=… look like (almost) removed? It works for me with 2.156.
Unknown User (jimklimov)
Seems like a Confluence formatting issue with many dashes in a line (so it is interpreted as a strike-out between a couple of those).
Unfortunately, my browsers won't let me edit the page today :\ so maybe someone else can pick it up later (likely need to escape some of the dashes with a backslash, or pre-formatting).
Unknown User (ch4unme)
Hi there,
I am trying to configure https certificate for Windows10. I am able to create the 'certreq.csr' file, but afterwords I am not able to request a SHA certificate from any provider. Could you please guide me on that. I would highly appreciate if you could provide me with any option with steps that can help to sign the certificate(or something that can self sign the certificate) to get that .p7b file. Please reply.
Unknown User (chendeshen)
good guidence.