Pulse Secure Command-line Launcher

The Pulse Launcher (pulselauncher.exe) is a standalone client-side command-line program that allows you to launch Pulse and connect to or disconnect from a Pulse server (Pulse Connect Secure or Pulse Policy Secure) without displaying the Pulse graphical user interface.

Pulse Launcher Usage Notes:

To use the Pulse Launcher program:

  1. Write a script, batch file, or application.
  2. Include a call to the Pulse Launcher executable, pulselauncher.exe.
  3. Include logic in your script, batch file, or application to handle the possible return codes.

Table 14 lists the Pulse Launcher arguments.

The following command shows the complete pulselauncher.exe command syntax:

pulselauncher.exe [-version|-help|-stop] [-url <url> -u <user> -p <password> -r <realm>] [-d <DSID> -url <url>] [-cert <client certificate> -url <url> -r <realm>] [-signout|-suspend|-resume -url <url>] [-t timeout)]]

Table 14: Pulse Launcher Arguments

Argument

Action

-version

Display the Pulse Launcher version information, then exit.

-help

Display available arguments information.

-stop

Stop Pulse and disconnect all active connections.

-url <url>

Specify the Pulse server URL.

-u <user>

Specify the username.

-p <password>

Specify the password for authentication.

-r <realm>

Specify the realm on the Pulse server.

-d <DSID>

Passes a cookie to Pulse Launcher for a specified Pulse server from another authentication mechanism when Pulse Launcher starts. When you use the -d argument, you must also specify the -url argument to specify the Pulse server.

-cert <client certificate>

Specify the certificate to use for user authentication. For <client certificate> use the string specified in the Issued To field of the certificate. When using the -cert argument, you must also specify the -url and -r <realm> arguments.

To use certificate authentication with the Pulse Launcher program, you must first configure the Pulse server to allow the user to sign in via user certificate authentication. You must also configure a trusted client CA on the Pulse server and install the corresponding client-side certificate in the Web browsers of end-users before running the Pulse Launcher.

If the certificate is invalid, the Pulse Launcher displays an error message on the command line and logs a message in the log file.

NOTE: If Pulse is launched through a browser, the browser handles certificate verification. If Pulse is launched through an application on Windows, the application handles certificate verification. If Pulse is launched through the Pulse Launcher on Windows, Pulse Launcher handles the expired or revoked client certificates.

-signout <url>

Signout disconnects and signs out from a specific server. Suspend puts an active connection in the suspend state without removing the session information from the server. Resume restores a suspended connection. Pulse can have multiple simultaneous connections so the -url argument is required when you use -signout, -suspend, or -resume.

-suspend <url>

-resume <url>

-t <timeout in seconds>

The amount of time allowed for the connection to take place before the attempt fails. Min = 45 (default), Max = 600.

Table15: Pulse Launcher Return Codes

Code

Description

-1

Pulse is not running.

0

Success.

1

A parameter is invalid.

2

Connection has failed or Pulse is unable to connect to the specified gateway.

3

Connection established with error.

4

Connection does not exist. Example: the command attempts to sign out from a server that has not been added on the Pulse UI.

5

User cancelled connection.

6

Client certificate error.

7

Timeout error.

8

No user connection allowed from Pulse UI.

9

No policy override from Pulse UI.

25

Invalid action for current connection state. This error code would occur if you tried to suspend or resume a connection that was disconnected.

100

General error.

Note: The return codes specified in Table10 refer to the executable’s return codes. On Windows, you can display the last error level with "echo %errorlevel%" (without quotes).  On OSX, the command is "echo $?" (without quotes).

Examples

The following command is a simple login application that captures the credentials the user enters, and passes the credentials as arguments to pulselauncher.exe:

pulselauncher.exe -u JDoe -p my$Pass84 -url https://int-company.portal.com/usr -r Users

pulselauncher return code: 0

The following Pulse Launcher example shows a certificate authentication:

pulselauncher.exe -url https://int-company.portal.com/usr -cert MyCert -url https://int-company.portal.com/usr  -r Users

pulselauncher return code: 0

The following example shows a command to use Pulse Launcher to specify a cookie (-d) for a specific Pulse server (-url):

pulselauncher.exe –d 12adf234nasu234 -url https://int-company.portal.com/usr

pulselauncher return code: 0

Related Documentation