Moveworks Agent Installation Guide
This document walks through the steps to install the Moveworks agent
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)
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: Follow this guide to get the Access Secret from Moveworks Setup.
Installation Method
- Change the directory to where you need to setup the agent. (Home Directory is recommended)
- Download the agent installation script using
curl
orwget
💡 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
or
sudo ./setup_agent.sh --docker
./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
directorycert.pem
Do you want to set up an LDAP connector? Enter [y/n]: Enter y
, if setting up an Active Directory connectiony
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
directorycompany_cert.pem
Do you want to use StartTLS (this is usually when using port 389) Enter [y/n]: If you are using LDAPS
with port636
, this should ben
Only choosey
if you want to use port389
withstartTLS
option.y
n
Do you want to set up a REST connector? Enter [y/n]: n
- not needed for LDAP-only integrationy
- setup REST connectiony
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 connectiony
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
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
-
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
Sample Moveworks Agent Configurations
LDAPS only (port 636)
bond_version: 2.10.1 # 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.10.1 # 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
LDAPS + Jira + Confluence + Azure Key Vault
bond_version: 2.10.1 # This will be set automatically by the configuration tool
ldap_config:
enabled: true
host: mvwks.net
ldap_service_password:
azure_entry:
secret_name: mw-ldap-secret
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:
azure_entry:
secret_name: mw-jira-secret
username: jira-moveworks
service: JIRA
CONFLUENCE:
enabled: true
header_decorators:
- basic_auth:
password:
azure_entry:
secret_name: mw-confluence-secret
username: confluence-moveworks
service: CONFLUENCE
secrets_provider_config:
azure:
default_vault: https://agent-dev-vaulxt.vault.azure.net/
Updated 7 days ago