Linux Agent Installation Guide

This document shows how to install and manage the Linux agent for Unmeshed Job Scheduling Platform. The agent is a Java-based application which runs natively on Linux machines and executes the scheduled jobs as configured on the Unmeshed Platform. The integration between agent and Unmeshed platform is protected by an access key and secret and happens over an HTTPS connection.

The Linux agent requires Java 22 or higher. The agent package includes a bundled JRE in the jdk folder, which is the recommended approach for consistent operation.

• Linux distribution (Ubuntu, CentOS, RHEL, Amazon Linux, etc.)
• Minimum 2GB RAM (4GB recommended)
• At least 4GB free disk space (for logs and temporary files)
• Network access to the Unmeshed platform

This zip file contains the foundational components required for the agent to operate:

• jdk/ - Java Development Kit folder containing the bundled JRE
• processes.yaml - Configuration file for the agent worker processes
• worker-logback.xml - Logging configuration for the worker processes
• monitor.jar - Monitoring and process management application
• start_monitor.sh - Shell script to start the monitoring service

This zip file contains the main agent execution files:

• workers.jar - Main worker execution engine (will be created/updated)
• monitor.jar - Monitoring application (optional, may be updated)

The installation process involves two main steps: installing prerequisites and then the agent binary. We'll use /unmeshed/agent/ as the installation directory.

1. Create the installation directory:

   bash

2. Download and extract the prerequisites package:

   bash

   You should see the following files and directories:

3. Set proper permissions:

   bash

1. Download and extract the agent binary package:

   bash

   You should see at least:

Edit the processes.yaml file to configure your agent:

The file should contain the following configuration:

The UNMESHED_BASH_CUSTOM_WORKERS parameter allows you to create multiple custom bash workers with different configurations. This is useful when you need different concurrency limits or want to separate workloads by namespace.

:::note For Linux agents, the ioThread parameter must always be set to false. :::

Each worker specification follows the format: namespace:name:maxConcurrentWorkers:false

• namespace: The namespace for this worker (e.g., "default", "prod", "dev")
• name: The worker name identifier that will be used in job definitions
• maxConcurrentWorkers: Maximum number of concurrent jobs this worker can handle
• ioThread: Must be set to false for Linux agents (required parameter)

Single Custom Worker:

This configuration will query for jobs in the prod namespace with the name high-priority-bash and can run up to 100 concurrent tasks.

Multiple Custom Workers:

This configuration creates three workers:

• default:standard-bash:50:false - Namespace default, jobs named standard-bash, concurrency of 50
• prod:high-priority-bash:100:false - Namespace prod, jobs named high-priority-bash, concurrency of 100
• dev:testing-bash:25:false - Namespace dev, jobs named testing-bash, concurrency of 25

No Custom Workers (Default):

Use descriptive names that represent your host machine's purpose:

• Environment-based: prod-web-server-bash, staging-db-bash, dev-testing-bash
• Function-based: batch-processing-bash, real-time-bash, backup-server-bash
• Location-based: us-east-1-bash, eu-west-1-bash, on-premise-bash

Why unique names matter: Using unique, descriptive names ensures that specific jobs will always run on the intended machine. For example, if you have a backup server with UNMESHED_BASH_CUSTOM_WORKERS: "default:backup-server-bash:10:false", only jobs defined with the name backup-server-bash in the default namespace will be executed on that machine.

• Environment Separation: Use different namespaces for dev, staging, and production
• Priority Management: Create high-priority workers with higher concurrency limits
• Resource Isolation: Separate different types of workloads (e.g., batch processing vs. real-time tasks)
• Testing: Dedicated workers for testing with lower concurrency limits

Edit the start_monitor.sh file to set the correct working directory:

Ensure the CURRENT_DIR variable is set correctly:

Important: Do not modify any other parts of this script unless you have specific requirements.

Create a systemd service file to manage the Unmeshed agent:

Add the following content:

Important Notes:

• User Field: Update User=ec2-user to the actual user that should run the process
• Working Directory: Ensure the path matches your installation directory
• Permissions: The specified user must have read/write access to the /unmeshed/agent/ directory

The agent creates logs in the working directory. Look for the following log entry to confirm successful startup:

You should see a log entry similar to:

If you need to run the agent manually (for debugging purposes):

Follow these steps to upgrade:

1. Stop the service:

   bash

2. Download and extract the new agent binary:

   bash

3. Start the service:

   bash

4. Verify the upgrade:

   bash

:::note The processes.yaml configuration file is not included in agent upgrades. If you need to update your configuration or add new parameters, please contact the Unmeshed support team for guidance on any required changes. :::

1. Service fails to start:

   • Check file permissions: ls -la /unmeshed/agent/
   • Verify Java installation: java -version
   • Check service logs: sudo journalctl -u unmeshed.service -n 50

2. Agent cannot connect to Unmeshed platform:

   • Verify network connectivity: ping <your-unmeshed-server>
   • Check authentication credentials in processes.yaml
   • Verify firewall settings

3. Permission denied errors:

   • Ensure the service user owns the /unmeshed/agent/ directory
   • Check file permissions: chmod +x /unmeshed/agent/start_monitor.sh

4. Java memory issues:

   • Adjust JVM memory settings in processes.yaml:
     • -Xms1024m (minimum heap size)
     • -Xmx1024m (maximum heap size)

The agent creates several log files:

• worker.log - Main worker process logs
• monitor.log - Monitor process logs
• systemd logs - Service management logs

1. File Permissions: Ensure only authorized users can access the agent configuration files
2. Network Security: Use HTTPS connections to the Unmeshed platform
3. Authentication: Keep your auth ID and token secure and rotate them regularly
4. Service User: Run the service with minimal required privileges
5. Firewall: Configure firewall rules to allow only necessary outbound connections

Adjust JVM memory settings based on your system resources:

Adjust based on your system's CPU cores and workload:

Optimize network communication:

1. Service Auto-restart: The systemd service is configured to automatically restart if the process crashes
2. Log Rotation: Consider implementing log rotation for long-running deployments
3. Monitoring: Set up monitoring for the service status and resource usage
4. Backup: Regularly backup your processes.yaml configuration file
5. Updates: Keep your Linux system updated for security patches
6. Resource Monitoring: Monitor CPU, memory, and disk usage during operation

• Creating Client Credentials
• Worker Configuration
• Process Execution
• Agent Management
• Windows Agent Installation
• IBMi/AS400 Agent Installation