Prerequisites

System/Server Requirements

The Moveworks Agent runs on Linux. Recommended OS with the following requirements (which are the same as “t3.medium” if hosted in AWS or a “B2” if hosted in Azure):

4 GB RAM
2 CPUs
30 GB of disk space

OS Requirements:

VM with Ubuntu 20.04 and above OR RHEL 8.0 and above.
Latest Version of Docker Engine or Podman must be pre-installed.

Server Setup

Procure server(s) matching the requirements outlined above. Note: Moveworks recommends at least 2 servers for high availability (HA).
Set up the Server with Docker or Podman. Note: Podman is recommended for a fully root-less implementation.
Recommended: If possible, Moveworks recommends that you use a separate (non-root) user for running the Moveworks Agent. This limits the granting of unintended access rights for the Agent.

Network Requirements

Ensure the server has proper network access to the on-premises system you intend Moveworks to connect to.
Ensure the server has proper network access upstream to the Moveworks Platform.
- Note: You can run the following curl command on the server to verify connection works: curl <auth_url> If Network connection is set up correctly, you should receive 404 page not found as the response.
- auth_url to be used:
  - For US commercial region: https://agent.moveworks.com/api/v1/auth
  - For US GovCloud region: https://agent.moveworksgov.com/api/v1/auth
  - For EU region: https://agent.am-eu-central.moveworks.com/api/v1/auth
  - For Canada region: https://agent.am-ca-central.moveworks.com/api/v1/auth
  - For Australia region: https://agent.am-ap-southeast.moveworks.com/api/v1/auth
- 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/

Credentials and Information 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 Authentication (Only applicable for customers using On-Premise Connections to make REST API Calls i.e. Jira, Confluence, Sharepoint, etc)
Base 64 encoded .pem cert file for LDAPS connection (typically this is the root cert in base64 format)

Moveworks Agent Credentials:

Access Key (Org Name): This is the same as your Customer ID which you should have used when setting up SSO.
Access Secret: To get the Access Secret, you must first generate it from the Agents module in Moveworks Setup:
1. Navigate to the Agents module in the left navigation bar under Core Platform.
1. Click on the Generate Secret button in the bottom right. A pop-up window will appear showing the Org Access Secret.
2. Copy the Org Access Secret and save it. You will need this value for the installation script.
IMPORTANT: Secure Your Org Access Secret
Please be advised that the API token for the Org Access Secret is displayed only once. It is imperative that you save it immediately for future use. Please handle the secret securely, and do not share it in plain text.

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

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

wget

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

Set the script’s permissions to allow execution.

Shell

chmod +x setup_agent.sh

Select the runtime between docker and podman and run the script

Shell

sudo ./setup_agent.sh --docker

Shell

./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 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

If the script fails to fetch the Agent Image from ECR, you can resolve this issue by following the steps here

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	Tenant Settings > General Information > Org Name
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.	Generate this in Moveworks Setup by following the instructions mentioned here.
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 an appropriate service name. This name should be representative of the system you are trying to connect to. If you have multiple instances, you can enumerate subsequent service names. (i.e. `JIRA`, `JIRA_2`). Please make note of this name as you’ll need to reference it in further steps.	`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

Create the connector
1. Go to Moveworks Setup
2. Select System Connectors or Custom Connectors depending on if the system you have added is used for a built-in functionality or for an Agent Studio use case.
3. Create Connector
4. Select On Premise Auth as the “Auth Config” and enter the Service Name from Step 6. If you are creating a Agent Studio connector, you must enter the Service Name and have it match the config in the agent from Step 6.
5. Save your connector.

Validating the Installation

**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

Check Agent Status After starting the agent, check the healthiness of the container by running docker ps or podman ps on the server.

$ # For Docker
$ sudo docker ps
$ 
$ # For Podman
$ podman ps

Start the Agent

$ ./setup_agent.sh --start

Fetching the Agent Image Without ECR

In some scenarios, enterprises have Servers with Firewall policies which block the ability for the VM to download the Agent image from ECR and automate the setup process, this is an alternate way to fetch the image in those scenarios.

You can start by visiting the Moveworks ECR Public Gallery and download the latest image tag .

docker pull public.ecr.aws/moveworks/agent:2.10.4

Save this image locally by running the command

docker save -o moveworks_agent.tar public.ecr.aws/moveworks/agent:2.10.4

This will save the image as moveworks_agent.tar

You can then load the image on the customer Server.

docker load -i moveworks_agent.tar

Image should show up on the machine on doing docker images

Now that the image has been added to the VM we can run the below commands to kick off the container.

docker run -d \
  -v /path/to/local/conf:/home/moveworks/agent/conf \
  -v /path/to/local/certs:/home/moveworks/agent/certs \
  -v /path/to/local/logs:/var/log/moveworks \
  -e LOG_LEVEL=INFO \
  public.ecr.aws/moveworks/agent:2.10.4

Other Tools

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)

Reconfigure the agent:

Shell

./setup_agent.sh —-configure

Upgrading the agent: This will upgrade all the agents at the server,

Shell

./setup_agent.sh —-upgrade

Common Errors and Troubleshooting

When running ./setup_agent.sh and the following is observed:

$ Failed to enable unit: Unit file docker service does not exist
$ [ERROR] Error enabling Docker service to start on boot
$ Failed to start Docker service: Unit docker service not found
$ [ERROR] Error starting Docker service

There may be an issue with the docker installation, to confirm do the following

Run the docker logs

$ docker logs --follow

See if the following error is observed:

$ exec /bin.sh: operation not permitted

If it is, uninstall docker and reinstall by following the steps for installing with the docker convenience script

Shell

1 Error installing Podman. Install Podman and Rerun
2 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.

Shell

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

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

Shell

1 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.

Shell

1 Error enabling linger
2 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.

Shell

1 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.

Shell

1 Podman version $podman_version does not meet the minimum required version $PODMAN_VERSION. Please upgrade Podman
2 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.

1 Error creating directory /etc/systemd/system. Create the directory and Reru
2 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.

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

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

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

Check whether systemd is correctly installed and functional.

1 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

Sample Moveworks Agent Configurations

LDAPS only (port 636)

yml

1 bond_version: 2.10.1 # This will be set automatically by the configuration tool
2 ldap_config:
3   enabled: true
4   host: mvwks.net
5   ldap_service_password:
6     encrypted_value: [REDACTED]
7   path_to_cert: /home/moveworks/agent/certs/cert.pem
8   port: 636
9   service_user: MVWKS\svc_moveworks
10   use_ssl: true
11 moveworks_config:
12   access_key: moveworks
13   auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
14   config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
15   moveworks_access_secret:
16     encrypted_value: [REDACTED]

LDAPS + Jira

yml

1 bond_version: 2.10.1 # This will be set automatically by the configuration tool
2 ldap_config:
3   enabled: true
4   host: mvwks.net
5   ldap_service_password:
6     encrypted_value: [REDACTED]
7   path_to_cert: /home/moveworks/agent/certs/cert.pem
8   port: 636
9   service_user: MVWKS\svc_moveworks
10   use_ssl: true
11 moveworks_config:
12   access_key: moveworks
13   auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
14   config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
15   moveworks_access_secret:
16     encrypted_value:[REDACTED]
17 rest_configs:
18   JIRA:
19     enabled: true
20     header_decorators:
21     - basic_auth:
22         password:
23           encrypted_value: [REDACTED]
24         username: service-moveworks
25     service: JIRA

LDAPS + Jira + Confluence + Azure Key Vault

yml

1 bond_version: 2.10.1 # This will be set automatically by the configuration tool
2 ldap_config:
3   enabled: true
4   host: mvwks.net
5   ldap_service_password:
6     azure_entry:
7       secret_name: mw-ldap-secret
8   path_to_cert: /home/moveworks/agent/certs/cert.pem
9   port: 636
10   service_user: MVWKS\svc_moveworks
11   use_ssl: true
12 moveworks_config:
13   access_key: moveworks
14   auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
15   config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
16   moveworks_access_secret:
17     encrypted_value:[REDACTED]
18 rest_configs:
19   JIRA:
20     enabled: true
21     timeout_ms: 60000 #increase default timeout to 60s. Value is in ms
22     header_decorators:
23     - basic_auth:
24         password:
25           azure_entry:
26             secret_name: mw-jira-secret
27         username: jira-moveworks
28     service: JIRA
29   CONFLUENCE:
30     enabled: true
31     header_decorators:
32     - basic_auth:
33         password:
34           azure_entry:
35             secret_name: mw-confluence-secret
36         username: confluence-moveworks
37     service: CONFLUENCE 
38 secrets_provider_config:
39   azure:
40     default_vault: https://agent-dev-vaulxt.vault.azure.net/