Moveworks Agent Installation Guide

This document walks through the steps to install the Moveworks agent

Suggest Edits

Prerequisites

Provided by the Customer:

URL of the AD Domain controller or load balancer that the agent should connect to
LDAP/AD Service account username & password (Only applicable for customers using On-Premises Active Directory, LDAP, etc)
REST Service account username & password (Only applicable for customers using On-Premise Jira, Confluence, Sharepoint, etc)
Firewall rules or HTTP Proxy settings in place to allow for outbound communication to https://public.ecr.aws and, to the Agent URL depending on region:
For US Commercial region: https://agent.moveworks.com/
For US GovCloud region: https://agent.moveworksgov.com/
For EU region: https://agent.am-eu-central.moveworks.com/
For Canada region: https://agent.am-ca-central.moveworks.com/
For Australia region: https://agent.am-ap-southeast.moveworks.com/
Base 64 encoded .pem cert file for LDAPS connection (typically this is the root cert in base64 format)
Two virtual machines per recommended specifications for High Availability setup (see System/Server Requirements section)

Provided by Moveworks:

Access Key (Org Name)
Access Secret

Installation Method

Change the directory to where you need to setup the agent. (Home Directory is recommended)

Download the agent installation script using curl or wget
💡 These links redirect to Github.

curl -fsSL https://get-agent.moveworks.com > setup_agent.sh

wget https://get-agent.moveworks.com/ --output-document setup_agent.sh

Set the script's permissions to allow execution.
```
chmod +x setup_agent.sh
```
Select the runtime between docker and podman and run the script
```
sudo ./setup_agent.sh --docker
```
or
```
./setup_agent.sh --podman
```

💡 Add sudo only if using Docker. Never use sudo when handling containers with Podman. This applies throughout the document.
💡 To initialise with host network (if ip-forwarding is disabled, or if you get a warning that container cannot access network) use --host-network
This command will install docker or podman if it is not already installed.

Configure the Setup

Example Prompts & Values:

Prompt	Description	Example Values
Enter username	Enter the server username you want to install the agent with.	`root` `ubuntu` `$(whoami)`
Enter the number of Agents to Start	At least 2 agents are recommended to be running in a single server.	`1` `2` `3`
Enter the agent version	The version of the agent which you want to install. (default is the latest)	Check latest version from https://gallery.ecr.aws/moveworks/agent
Configuration file found. Do you want to set a new configuration? [y/n]:	This only happens when a configuration file already exists. You can choose to re-configure here.	y/n
Do you want to add required Certificates( If the agent is meant to connect to a Directory system using LDAP)?	You can add Certificates here in the certs directory. Rerun the script for changes to apply.	y/n

Configuring the Agent

Example Prompts & Values:

Prompt	Description	Example Values
Do you want to configure an external secrets manager? [No(1), AWS Secrets Manager(2), Azure Key Vault(3)]:	Select an option depending on how the service account credentials are created. For example: `3`, if secrets are stored in Azure Key Vault.	`1` `2` `3`
Enter the access_key (org name):	This will be provided by Moveworks, use all lowercase characters when entering the value	`Value provided by Moveworks`
Enter the access_secret:	This is the Access Secret that will be provided by Moveworks. If you configured an external secrets manager to store the Access Secret, it will prompt for input, enter secret URI to where the secret is hosted.	`Value provided by Moveworks`
Enter the auth_url:	Select the `auth_url` depending on data center requirements. Confirm with the Moveworks team, if unsure.	For - US Commercial: `https://agent.moveworks.com/api/v1/auth` US GovCloud: `https://agent.moveworksgov.com/api/v1/auth` Canada: `https://agent.am-ca-central.moveworks.com/api/v1/auth` EU: `https://agent.am-eu-central.moveworks.com/api/v1/auth` Australia: `https://agent.am-ap-southeast.moveworks.com/api/v1/auth`
Enter the config_url:	Select the `config_url` depending on data residency requirements. Confirm with the Customer Success team, if unsure.	For - US Commercial: `https://agent.moveworks.com/api/v1/config` US GovCloud: `https://agent.moveworksgov.com/api/v1/config` Canada: `https://agent.am-ca-central.moveworks.com/api/v1/config` EU: `https://agent.am-eu-central.moveworks.com/api/v1/config` Australia: `https://agent.am-ap-southeast.moveworks.com/api/v1/config`
Do you want to set up agent to use a proxy? Enter [y/n]:	optional, default is `n`	`y` `n`
Enter the proxy url (leave blank for transparent proxies):
Do you want to use a cert with the proxy? Enter [y/n]:		`y` `n`
[y] Enter the full name of the pem file including the extension:	Enter the full filename of your cert and place the cert in `/certs` directory	`cert.pem`
Do you want to set up an LDAP connector? Enter [y/n]:	Enter `y`, if setting up an Active Directory connection	`y` `n`
Do you want to set up an LDAP forest? Enter [y/n]:	Select this option to configure multiple ldap domains. This will repeat the next few steps depending on how many domains you want to setup.	`y` `n`
Enter the FQDN of the LDAP server (do not include ldap:// prefix):	No protocol prefix or port needed.	`company.net`
Enter the port to use e.g: 389 (LDAP), 636 (LDAPS), 3268 (LDAP Global Catalog), 3269 (LDAPS Global Catalog):	Moveworks recommends port 636 for LDAPS, you can use port 389 for LDAP for testing purposes during the initial setup.	`636`
Enter the LDAP service account username:	For Active Directory, LDAP Service User is formatted as a netbios domain name with a backlash and then the service account svc_moveworks` Please note that this may sometimes require escaping, e.g.`MVWKS ame.	`MVWKS\svc_moveworks`
Enter the ldap service password:	Please type (do not paste) the password. This is then encrypted before being saved to disk. The password is masked on entry so you will not see characters as you type.	service account password
Do you want to set up LDAP to connect with SSL? Enter [y/n]:	`y` will allow you to add the local path to your cert (`.pem` file)	`y` `n`
Do you want LDAP to connect with a cert (.pem file)? Note: this is required for LDAPS connections Enter [y/n]:	`y` will allow you to add the local path to your cert (`.pem` file)	`y` `n`
Enter the full name of the pem file including the extension:	Enter the full filename of your cert and place the cert in `/certs` directory	`company_cert.pem`
Do you want to use StartTLS (this is usually when using port 389) Enter [y/n]:	If you are using `LDAPS` with port `636`, this should be `n` Only choose `y` if you want to use port `389` with `startTLS` option.	`y` `n`
Do you want to set up a REST connector? Enter [y/n]:	`n` - not needed for LDAP-only integration `y` - setup REST connection	`y` `n`
Enter the service name (Ex. JIRA, CONFLUENCE, CHERWELL, SHAREPOINT, MSTEAMS, MANAGE_ENGINE, SNOW):	Enter the appropriate service name.	`JIRA`
Do you want to setup a header decorator? Enter [y/n]:	`y` - in order to set up authentication for the REST connection	`y`
What type of header decorator? [KV pair(1), file(2), basic auth(3), Oauth2 Client Credentials(4), Oauth2 Client Credentials Basic Auth (5), Oauth2 Refresh Token (6), Custom Auth(7)]:	Select the appropriate header decorator (typically for auth). You will then be guided to provide the necessary information for the given header type.	`3`

Other Tools

Validate OS version & Connectivity - This command will validate the operating system version, check for connectivity to Moveworks servers, and ensure required folders and permissions are set.
```
./setup_agent.sh --validate
```
Stop all running agents — This will shut down all running agents.
```
./setup_agent.sh --stop
```
Fetch LDAP certificate from the server (openssl required for this script to work)
```
./setup_agent.sh --fetch
```
Starting an agent
```
./setup_agent.sh --start
```
Reconfigure the agent:
```
./setup_agent.sh —-configure
```
Upgrading the agent: This will upgrade all the agents at the server,
```
/setup_agent.sh —-upgrade
```

Common Errors and Troubleshooting

Error installing Podman. Install Podman and Rerun
Error installing Docker, Install Docker and Rerun

The script allows Docker/Podman installation only for select Linux Distributions. Manually install Docker/Podman and then rerun the script with the same options.

Error adding Podman repository to package sources. Install Podman and Rerun
Error adding GPG key for Podman repository. Install Podman and Rerun

Ubuntu versions lower than 20.10 don't support Podman via the official repository. Manually install Docker/Podman and then rerun the script with the same options.

Error installing yum-utils to install docker. Install docker and Rerun

For non s390x RHEL based distributions, we need to add yum-utils to install Docker. Manually install Docker/Podman and then rerun the script with the same options.

Error enabling linger
Loginctl not installed. Error enabling linger

If loginctl is not installed, script will continue installation.
It may not be an issue with Docker based containers but for Podman, Agent might stop running when user session ends/dies.

Warning: System does not use systemd. Docker service may not start on boot

If systemctl is not installed, there may be issues with the the Docker/Podman container restarting on boot.

Podman version $podman_version does not meet the minimum required version $PODMAN_VERSION. Please upgrade Podman
Docker version $docker_version does not meet the minimum required version $DOCKER_VERSION. Uninstall Docker and rerun.

If docker/podman is installed and the versions don’t meet the minimum requirement, it will give a warning for the same.

Error creating directory /etc/systemd/system. Create the directory and Reru
Error creating directory $HOME/.config/systemd/user. Create the directory and Rerun

For Podman containers, systemd file needs to be added to this directory. If this directory does not exist, we create said directory. If the operation fails, manually create that directory and rerun the script with the same options.

Error renaming Podman container CONTAINER_NAME to moveworks_agent_{i}
Error generating systemd unit file for Podman container moveworks_agent_

Check old/unused containers/networks/volumes and remove them `podman system prune`

Error reloading systemd daemon for Podman containers
Error enabling service for Podman container moveworks_agent_
"Error disabling or stopping service for Podman container
Error reloading systemd daemon for Podman containers.

Check whether systemd is correctly installed and functional.

Error: Failed to pull agent image with version '$AGENT_VERSION' using podman from ECR repository '$ECR_URL'.

Check whether entered version is correct and the image corresponding to the version exists at https://gallery.ecr.aws/moveworks/agent

Installation Method (OLD)

Pre-installation steps:

Install the latest version of Docker or Podman on the server using the instructions from the Docker Website for your OS.
Ensure the Docker (or Podman) daemon is configured to start on boot.

🚧
DO NOT use the snap installation of Docker

Following the receipt of the encrypted email from your Moveworks Customer Success Team, proceed with the following steps to install the Moveworks agent on your Linux virtual machine(s).

📘
Podman customers
If using podman instead of docker, substitute podman for all of the docker commands in the following instructions

Create a moveworks folder in the server's home directory. After creating, open the moveworks folder.
```
mkdir moveworks
cd moveworks
```
Pull Container Image from Public ECR Repository: Retrieve the latest Docker image of the agent from the public AWS ECR (Elastic Container Registry) repository by running the following command from the moveworks folder.
```
docker pull <version>
```
In the command above replace <version> with the latest version from the public ECR Repo. You can click the copy button on the link above, to grab the latest version.

Copy the helper script from the container to your virtual machine by running the following commands. Use the same <version> value from above.

docker create --name temp <version> # create a readable container layer
docker cp temp:/moveworks/services/bond/runtime/scripts/helper.sh ./helper.sh # copy the file from the temp layer
docker rm -f temp # remove the temp layer

Setup Agent folders & permissions (Note: Some of these operations may require administrative privileges (sudo) to complete.)

sudo ./helper.sh --init # This creates a folder structure for storing agent configs, logs, etc.
sudo ./helper.sh --permissions # This ensures proper permissions are set on the VM for the agent to run

Configure the Agent: Run the command ./helper.sh --configure This command initiates an interactive guide to help you through the configuration process by asking you the questions in the table below. This step enables you to provide specific settings and preferences for the agent's operation. Note: This step is not required if you have received a pre-configured configuration file from your Moveworks Customer Success team. In this case, simply place the configuration file in the conf directory.

Example Prompts & Values:

Prompt	Description	Example Values
Do you want to configure an external secrets manager? [No(1), AWS Secrets Manager(2), Azure Key Vault(3)]:	Select an option depending on how the service account credentials are created. For example: `1`, if account is created on Active Directory.	`1` `2` `3`
Enter the access_key (org name):	This will be provided by your Customer Success team, use all lowercase characters when entering the value	`Value provided by Moveworks`
Enter the access_secret:	This is the Moveworks Org Access Secret that will be provided by your Customer Success team. If you configured an external secrets manager to store the Org Access Secret, it will prompt for the secret URI to where the secret is hosted.	`Value provided by Moveworks`
Enter the auth_url:	Select an `auth_url` depending on data residency requirements. Confirm with the Customer Success team, if unsure.	For - US Commercial: `https://agent.moveworks.com/api/v1/auth` US GovCloud: `https://agent.moveworksgov.com/api/v1/auth` Canada: `https://agent.am-ca-central.moveworks.com/api/v1/auth` EU: `https://agent.am-eu-central.moveworks.com/api/v1/auth` Australia: `https://agent.am-ap-southeast.moveworks.com/api/v1/auth`
Enter the config_url:	Select a `config_url` depending on data residency requirements. Confirm with the Customer Success team, if unsure.	For - US Commercial: `https://agent.moveworks.com/api/v1/config` US GovCloud: `https://agent.moveworksgov.com/api/v1/config` Canada: `https://agent.am-ca-central.moveworks.com/api/v1/config` EU: `https://agent.am-eu-central.moveworks.com/api/v1/config` Australia: `https://agent.am-ap-southeast.moveworks.com/api/v1/config`
Do you want to set up agent to use a proxy? Enter [y/n]:	optional, default is `n`	`y` `n`
Enter the proxy url (leave blank for transparent proxies):
Do you want to use a cert with the proxy? Enter [y/n]:		`y` `n`
[y] Enter the full name of the pem file including the extension:	Enter the full filename of your cert and place the cert in `/certs` directory	`cert.pem`
Do you want to set up an LDAP connector? Enter [y/n]:	Enter `y`, if setting up an Active Directory connection	`y` `n`
Do you want to set up an LDAP forest? Enter [y/n]:	Select this option to configure multiple ldap domains. This will repeat the next few steps depending on how many domains you want to setup.	`y` `n`
Enter the FQDN of the LDAP server (do not include ldap:// prefix):	No protocol prefix or port needed.	`company.net`
Enter the port to use e.g: 389 (LDAP), 636 (LDAPS), 3268 (LDAP Global Catalog), 3269 (LDAPS Global Catalog):	Moveworks recommends port 636 for LDAPS, you can use port 389 for LDAP for testing purposes during the initial setup.	`636`
Enter the LDAP service account username:	For Active Directory, LDAP Service User is formatted as a netbios domain name with a backlash and then the service account svc_moveworks` Please note that this may sometimes require escaping, e.g.`MVWKS ame.	`MVWKS\svc_moveworks`
Enter the ldap service password:	Please type (do not paste) the password. This is then encrypted before being saved to disk. The password is masked on entry so you will not see characters as you type.	service account password
Do you want to set up LDAP to connect with SSL? Enter [y/n]:	`y` will allow you to add the local path to your cert (`.pem` file)	`y` `n`
Do you want LDAP to connect with a cert (.pem file)? Note: this is required for LDAPS connections Enter [y/n]:	`y` will allow you to add the local path to your cert (`.pem` file)	`y` `n`
Enter the full name of the pem file including the extension:	Enter the full filename of your cert and place the cert in `/certs` directory	`company_cert.pem`
Do you want to use StartTLS (this is usually when using port 389) Enter [y/n]:	If you are using `LDAPS` with port `636`, this should be `n` Only choose `y` if you want to use port `389` with `startTLS` option.	`y` `n`
Do you want to set up a REST connector? Enter [y/n]:	`n` - not needed for LDAP-only integration `y` - setup REST connection	`y` `n`
Enter the service name (Ex. JIRA, CONFLUENCE, CHERWELL, SHAREPOINT, MSTEAMS, MANAGE_ENGINE, SNOW):	Enter the appropriate service name.	`JIRA`
Do you want to setup a header decorator? Enter [y/n]:	`y` - in order to set up authentication for the REST connection	`y`
What type of header decorator? [KV pair(1), file(2), basic auth(3), Oauth2 Client Credentials(4), Oauth2 Client Credentials Basic Auth (5), custom auth(6)]:	Select the appropriate header decorator (typically for auth). You will then be guided to provide the necessary information for the given header type.	`3`

Add required certificates: If the agent is meant to connect to a Directory system using LDAPS then add the root certificate to the following directory as a .pem file /moveworks_agent/certs .
Start the Agent: This command starts the agent on the customer VM.
```
./helper.sh --start
```
1. For deployments requiring FIPS compliance use --fips flag
```
./helper.sh --start --fips
```
Verify the agent has started successfully by running docker ps

Also, ensure that there are no errors in the agent logs by running tail -f logs/moveworks.agent.<container_id>.INFO.log
Start a second Agent: Once you have verified the Moveworks agent has started successfully, Moveworks recommends starting another agent so that there are at least 2 agents running on the VM. This helps improve stability and reliability of the agent.

📘
Note: For ServiceNow Connections
If you are routing ServiceNow traffic through your Moveworks agent, Moveworks recommends running 4 VMs with 1 agent each.

Helpful Tools

Some helpful scripts are shipped as part of a helper script in the agent package.

Validate OS version & Connectivity - This command will validate the operating system version, check for connectivity to Moveworks servers, and ensure required folders and permissions are set.
```
./helper.sh --validate
```
Stop all running agents — This will shut down all running agents.
```
./helper.sh --stop
```
Fetch LDAP certificate from the server (openssl required for this script to work)
```
./helper.sh --fetch
```

Reconfiguring the Agent

If you need to edit the config simply open the config file with a text editor and edit the fields you need.

Navigate into into the conf directory e.g: cd conf
Open the agent_config.yml with your favorite text editor such as vi or nano e.g: vi agent_config.yml
For sensitive fields like passwords, simply remove the encrypted_value field and replace it with the value field and the actual value in plaintext (this will automatically get encrypted on startup of the agent).
```
moveworks_config:
	...
	moveworks_access_secret:
		value: newOrgAccessSecretValue
ldap_config:
	...
	ldap_service_password:
		value: newldappassword
```
Once the agent_config.yml file has been updated with the new credentials, be sure to restart the current container. You can do this by executing the built-in commands ./helper.sh --stop followed by ./helper.sh --start from the moveworks folder.

Updating the Agent

Stop currently running agents. You can use the script under the tools directory.
```
./helper.sh --stop
```
Pull the latest docker image from ECR public repo.
```
docker pull <version>
```
Initialize the agent - Run the init command to rename the version as the latest.
```
./helper.sh --init
```
Restart the Moveworks agent - If there were multiple agents running just run this command again to start additional agents.
```
./helper.sh --start
```
Verify the agents have started up successfully - Run docker ps to ensure the agents are healthy.

Verify there are no errors in the logs

tail -f logs/moveworks.agent.<container_id>.INFO.log

Sample Moveworks Agent Configurations

LDAPS only (port 636)

bond_version: 2.8.5 # This will be set automatically by the configuration tool
ldap_config:
  enabled: true
  host: mvwks.net
  ldap_service_password:
    encrypted_value: [REDACTED]
  path_to_cert: /home/moveworks/agent/certs/cert.pem
  port: 636
  service_user: MVWKS\svc_moveworks
  use_ssl: true
moveworks_config:
  access_key: moveworks
  auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  moveworks_access_secret:
    encrypted_value: [REDACTED]

LDAPS + Jira

bond_version: 2.8.5 # This will be set automatically by the configuration tool
ldap_config:
  enabled: true
  host: mvwks.net
  ldap_service_password:
    encrypted_value: [REDACTED]
  path_to_cert: /home/moveworks/agent/certs/cert.pem
  port: 636
  service_user: MVWKS\svc_moveworks
  use_ssl: true
moveworks_config:
  access_key: moveworks
  auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  moveworks_access_secret:
    encrypted_value:[REDACTED]
rest_configs:
  JIRA:
    enabled: true
    header_decorators:
    - basic_auth:
        password:
          encrypted_value: [REDACTED]
        username: service-moveworks
    service: JIRA

Updated about 1 month ago

Moveworks Agent Installation Guide

Prerequisites

Provided by the Customer:

Provided by Moveworks:

Installation Method

Other Tools

Common Errors and Troubleshooting

Installation Method (OLD)

Pre-installation steps:

🚧
DO NOT use the snap installation of Docker

📘
Podman customers

📘
Note: For ServiceNow Connections

Helpful Tools

Reconfiguring the Agent

Updating the Agent

Sample Moveworks Agent Configurations

LDAPS only (port 636)

LDAPS + Jira

Prerequisites

Provided by the Customer:

Provided by Moveworks:

Installation Method

Other Tools

Common Errors and Troubleshooting

Installation Method (OLD)

Pre-installation steps:

🚧DO NOT use the snap installation of Docker

📘Podman customers

📘Note: For ServiceNow Connections

Helpful Tools

Reconfiguring the Agent

Updating the Agent

Sample Moveworks Agent Configurations

LDAPS only (port 636)

LDAPS + Jira

🚧
DO NOT use the snap installation of Docker

📘
Podman customers

📘
Note: For ServiceNow Connections