Hermes for SAP ECC

Choosing an Installation Method

Use the native installer or package for single-instance deployments. Choose the ZIP method to run multiple independent Hermes instances on a single machine or to deploy to environments without a package manager.

System Requirements

• OS:
  • Windows 10 / Windows Server 2019 or later (x64)
  • Any recent x64 Linux distribution with glibc >= 2.28
• Memory: 500 MB available RAM
• Disk: 1 GB (300 MB for installation, remainder for logs)
• CPU: Any modern x64 CPU
• Windows only: Microsoft Visual C++ Redistributable 2013 is required by the bundled node-rfc dependency

Windows — Native Installer (.exe)

This is the recommended method for Windows users running a single Hermes instance.

Installation

1. Download the latest Hermes Windows installer:

   • Production: Hermes-Windows-Installer.exe
   • Testing/development: Hermes-Windows-Installer.exe

2. Right-click the installer and select Run as administrator.

3. Run the installation wizard. Accept the license agreement and choose an installation directory (the default is C:\Program Files\Graphite Hermes\).

4. Once the wizard completes, the installer creates a production.json configuration file in the installation directory. Open it in a text editor and fill in your environment-specific settings. See Configuration.

5. Open Windows Services (services.msc), locate Graphite Hermes, and start it.

Uninstalling

Open Add or Remove Programs, find Graphite Hermes, and click Uninstall. This stops the service and removes all application files.

Updating

1. Download the latest installer from the links above.

2. Right-click and select Run as administrator.

When you run the new installer, it detects your existing installation, stops the running service, replaces the application files, and restarts the service. Your production.json remains unchanged.

Windows — ZIP Installation

Use this method to run multiple Hermes instances on the same Windows machine — for example, one instance per SAP system or environment. Each instance lives in its own directory and registers as a separate Windows service.

Installation

1. Download the latest Hermes Windows ZIP:

   • Production: hermes.windows.zip
   • Testing/development: hermes.windows.zip

2. Extract the ZIP to the directory where you want this instance to live, for example C:\hermes-primary\. For a second instance, extract to a separate directory such as C:\hermes-secondary\.

3. Open production.json in the extracted directory and fill in your environment-specific settings. If it does not exist yet, create it from production.example.json first. See Configuration.

   cmd

   copy /Y "C:\hermes-primary\production.example.json" "C:\hermes-primary\production.json"

4. To register the instance as a Windows service, right-click Command Prompt and select Run as administrator, then run install.cmd from the instance directory:

   cmd

   "C:\hermes-primary\install.cmd"

   The script prompts you for a unique service name. This name identifies the service in Windows Services and is saved into production.json as windowsServiceName.

5. Open Windows Services (services.msc), locate your named service, and start it.

Note: Each instance must have a unique service name so that Windows can manage them independently. If two instances share the same name, Windows overwrites the first service definition, causing one instance to stop working. Use a descriptive name for each instance (e.g., Hermes-Primary, Hermes-Secondary).

Uninstallation

1. From an administrator Command Prompt, uninstall the service. The service name is the one you entered during installation, and can also be found in production.json as windowsServiceName:

   cmd

   "C:\hermes-primary\node.exe" "C:\hermes-primary\dist\win-svc.js" uninstall --name "Your Service Name"

2. Once the service is uninstalled, delete the instance directory:

   cmd

   rmdir /s /q "C:\hermes-primary"

Updating

Run the self-updater from an administrator Command Prompt:

"C:\hermes-primary\node.exe" "C:\hermes-primary\dist\update.js" <build>

Replace <build> with release for production or develop for testing/development.

This command stops the service, downloads the latest build, applies it, and restarts the service. Your production.json remains unchanged.

Linux — Native Package (.deb / .rpm)

This is the recommended method for Linux users running a single Hermes instance. It installs Hermes to /opt/graphite-hermes/ and registers a systemd service that runs under a dedicated hermes system user.

Post-install checklist (Linux package)

Run this checklist after installing either the .deb or .rpm package:

1. Configure /opt/graphite-hermes/production.json.
2. Start Hermes manually:
   Bash

   sudo systemctl start graphite-hermes

3. Verify service status:
   Bash

   sudo systemctl status graphite-hermes

Expected behavior: On first install, the package enables graphite-hermes at boot but does not start it. Hermes requires a valid production.json before it can connect to SAP and Graphite. Start the service manually after completing your configuration.

Installation — Debian / Ubuntu (.deb)

1. Download the latest Hermes .deb package:

   • Production: hermes.linux.deb
   • Testing/development: hermes.linux.deb

2. Install the package:

   Bash

   sudo apt-get install -y /path/to/hermes.linux.deb

3. Follow the Post-install checklist (Linux package).

Installation — Red Hat / Rocky Linux / Amazon Linux (.rpm)

1. Download the latest Hermes .rpm package:

   • Production: hermes.linux.rpm
   • Testing/development: hermes.linux.rpm

2. Install the package:

   Bash

   sudo rpm -i /path/to/hermes.linux.rpm

3. Follow the Post-install checklist (Linux package).

Uninstallation

Debian / Ubuntu:

sudo apt-get remove -y graphite-hermes   # uninstalls the graphite-hermes package

Red Hat / Rocky Linux / Amazon Linux:

sudo rpm -e graphite-hermes   # uninstalls the graphite-hermes package

Note: During uninstallation, the package manager copies your production.json configuration file to /opt/graphite-hermes-production.json.bak. You can use this backup to restore your settings if you reinstall later.

Updating

1. Download the latest package from the links above.

2. Debian / Ubuntu:

   Bash

   sudo apt-get install -y /path/to/hermes.linux.deb

   Red Hat / Rocky Linux / Amazon Linux:

   Bash

   sudo rpm -U /path/to/hermes.linux.rpm

This command stops the service, replaces the application files, and restarts the service. Your production.json remains unchanged.

Linux — ZIP Installation

Use this method to run multiple Hermes instances on the same Linux machine (for example, one instance per SAP system) or to deploy to minimal environments that do not include apt or rpm. Store each instance in its own directory and register it as a separate systemd service.

Post-install checklist (Linux ZIP)

Run this checklist after extracting and registering each ZIP instance:

1. Configure /opt/<your-instance>/production.json.
2. Start the instance manually:
   Bash

   sudo systemctl start <service-name>

3. Verify service status:
   Bash

   sudo systemctl status <service-name>

Expected behavior: install.sh enables <service-name> at boot but does not start the service. Hermes requires a valid production.json before it can run.

Installation

1. Download the latest Hermes Linux ZIP:

   • Production: hermes.linux.zip
   • Testing/development: hermes.linux.zip

2. Extract the ZIP to the directory where you want this instance to live:

   Bash

   sudo mkdir -p /opt/graphite-hermes-primary
   sudo unzip /path/to/hermes.linux.zip -d /opt/graphite-hermes-primary

   For a second instance, extract to a separate directory:

   Bash

   sudo mkdir -p /opt/graphite-hermes-secondary
   sudo unzip /path/to/hermes.linux.zip -d /opt/graphite-hermes-secondary

3. Open production.json in a text editor and fill in your environment-specific settings. If it does not exist yet, create it from production.example.json first. See Configuration.

   Bash

   sudo cp /opt/graphite-hermes-primary/production.example.json /opt/graphite-hermes-primary/production.json
   sudo nano /opt/graphite-hermes-primary/production.json

4. Register the instance as a systemd service by running install.sh from the instance directory:

   Bash

   sudo /opt/graphite-hermes-primary/install.sh

   When you run the script, it prompts you for a unique service name and creates a systemd unit file at /etc/systemd/system/<service-name>.service scoped to that directory.

5. Follow the Post-install checklist (Linux ZIP).

Note: Each instance must have a unique service name so that systemd can manage them independently. If two instances share the same name, the second registration overwrites the first unit file, causing one instance to stop working. Use a descriptive name for each instance (e.g., graphite-hermes-primary, graphite-hermes-secondary).

Note: systemd runs the service as the user who invoked install.sh via sudo, inheriting that user's file-system and network permissions. The service can only access files and network resources that the invoking user has permission to reach. To run the service as a different user, edit the User= line in the unit file at /etc/systemd/system/<service-name>.service before starting the service.

Uninstalling (Linux ZIP)

sudo systemctl stop <service-name>
sudo systemctl disable <service-name>
sudo rm /etc/systemd/system/<service-name>.service
sudo systemctl daemon-reload
sudo rm -rf /opt/graphite-hermes-primary

Updating

Run the self-updater from within the instance directory:

sudo /opt/graphite-hermes-primary/node /opt/graphite-hermes-primary/dist/update.js <build>

Replace <build> with release for production or develop for testing/development.

When you run this command, it stops the service, downloads the latest build, applies the update, and restarts the service. Your production.json remains unchanged.

Configuration

After installation, open production.json in the Hermes installation directory and update it with your environment-specific settings before starting the service. The installer automatically creates this file from production.example.json on first install.

{  
    "graphiteApiUrl": "https://app.graphiteconnect.com",  
    "graphiteApiKey": "<YOUR_GRAPHITE_API_KEY>",  
    "graphiteInterfaceName": "sap",  
    "adapterType": "SAP_EH8",  
    "windowsServiceName": "Graphite Hermes",  
    "ECCParams": {  
        "dest": "MME",  
        "user": "<YOUR_SAP_USER>",  
        "passwd": "<YOUR_SAP_PASSWORD>",  
        "ashost": "<YOUR_SAP_HOST>",  
        "sysnr": "00",  
        "client": "800",  
        "lang": "EN"  
    }  
}

Note: Ensure production.json contains valid JSON. Restart Hermes for any configuration changes to take effect.

For information on generating a Graphite API key, see the Graphite Connect help center.

For information on encrypting the configuration file to protect sensitive credentials, see the Encryption section.

Update notifications (native and ZIP installs)

Hermes can check for new builds in the background and log a warning when an update is available. This check is notification-only and does not auto-install updates.

After each check, Hermes also writes the latest check result to update-status.json in the Hermes installation directory.

Supported production.json settings:

{
  "updateCheckEnabled": true,
  "updateChannel": "release",
  "updateCheckIntervalHours": 24,
  "updateNotifyCooldownHours": 24,
  "updateCheckTimeoutMs": 3000
}

• updateCheckEnabled: enable/disable background update checks.
• updateChannel: release or develop.
• updateCheckIntervalHours: how often Hermes checks for updates.
• updateNotifyCooldownHours: minimum time before repeating the same update warning.
• updateCheckTimeoutMs: HTTP timeout for the update check.

Note: For production environments, keep updateChannel set to release.

Note: Changes to these settings are loaded at process start. Restart the Hermes service after editing production.json.

Updating Hermes

Replace <build> with release for production or develop for testing/development. For native installers and packages, download from the corresponding build link in the installation sections above.

Migrating from a Previous Installation

Existing ZIP users moving to the native installer or package (single instance)

If you were previously running Hermes from a ZIP and want to switch to the native installer or package:

1. Back up your configuration:

   Bash

   # Linux
   cp /path/to/hermes/production.json ~/production.json.bak

   On Windows, copy production.json from the Hermes directory to a safe location.

2. Stop and uninstall the old service:

   Linux (systemd):

   Bash

   sudo systemctl stop <your-service-name>
   sudo systemctl disable <your-service-name>
   sudo rm /etc/systemd/system/<your-service-name>.service
   sudo systemctl daemon-reload

   Windows (administrator Command Prompt):

   cmd

   "C:\path\to\hermes\node.exe" "C:\path\to\hermes\dist\win-svc.js" uninstall --name "Your Service Name"

3. Download the latest ZIP for your platform:

   • Linux (release): hermes.linux.zip
   • Linux (develop): hermes.linux.zip
   • Windows (release): hermes.windows.zip
   • Windows (develop): hermes.windows.zip

4. Restore your configuration by copying your backed-up production.json over the new one:

   Bash

   # Linux
   sudo unzip -o /path/to/hermes.linux.zip -d /opt/your-hermes-instance

   On Windows, copy the backed-up file to C:\Program Files\Graphite Hermes\production.json.

5. Start the service.

Existing ZIP users staying on ZIP (multiple instances)

If you are running multiple instances, do not use the native package — it installs a single shared instance to /opt/graphite-hermes/ and will not be aware of your existing custom service definitions.

The update script (update.js) changed significantly in recent versions of Hermes. For existing ZIP installations on older versions, perform a fresh installation per instance rather than running the updater. This approach gives you a clean, known-good state. Once you migrate each instance to the current ZIP layout, use the normal ZIP update flow described in Updating Hermes.

For each instance:

1. Back up your configuration and systemd unit file (Linux) before making any changes:

   Bash

   cp /opt/your-hermes-instance/production.json ~/production-instance.json.bak
   cp /etc/systemd/system/<your-service-name>.service ~/your-service-name.service.bak

   On Windows, copy production.json from the instance directory to a safe location.

2. Stop and disable the existing service:

   Linux:

   Bash

   sudo systemctl stop <your-service-name>
   sudo systemctl disable <your-service-name>

   Windows (administrator Command Prompt):

   cmd

   "C:\path\to\hermes-instance\node.exe" "C:\path\to\hermes-instance\dist\win-svc.js" uninstall --name "Your Service Name"

3. Download the latest ZIP for your platform:

   • Linux: hermes.linux.zip
   • Windows: hermes.win32.zip

4. Extract the new ZIP over the existing instance directory, replacing all application files:

   Linux:

   Bash

   sudo unzip -o hermes.linux.zip -d /opt/your-hermes-instance

   Windows: Extract the ZIP contents into the existing instance folder, choosing to overwrite all files when prompted.

5. Restore your production.json from the backup you made in step 1, because extracting the ZIP may have overwritten it with the example file:

   Linux:

   Bash

   sudo cp ~/production-instance.json.bak /opt/your-hermes-instance/production.json

   On Windows, copy the backed-up file back into the instance directory.

6. Re-register the service:

   Linux — run install.sh and enter the same service name as before when prompted:

   Bash

   sudo /opt/your-hermes-instance/install.sh

   Important (Linux): If your previous systemd unit file contained custom Environment= entries (for example, self-signed certificate paths or a custom LD_LIBRARY_PATH), re-apply those entries to the new unit file at /etc/systemd/system/<service-name>.service before starting the service. Refer to your backup from step 1 to identify which entries to re-add.

   Windows — run install.cmd and enter the same service name as before when prompted:

   cmd

   "C:\path\to\hermes-instance\install.cmd"

7. Start the service:

   Linux:

   Bash

   sudo systemctl start <your-service-name>

   Windows: Open Windows Services (services.msc), locate your service, and start it.

8. Repeat for each instance using its own directory and service name.

Logging

Hermes logs output to a file in the logs directory by default. Hermes rotates the log file when it reaches 20 MB. Graphite captures all interface-related errors, which you can view in the interfaces administration tool.

For SAP ECC interfaces, use the adapterType of SAP_EH8.

Encryption

Due to the sensitivity of the data contained within this file, it is highly encouraged to use this encryption.

Hermes includes an encryption utility to encrypt and decrypt the production.json file. At runtime, Hermes decrypts the configuration file in memory without writing the decrypted content to disk.

The provided utility uses AES 256 CTR encryption using the NodeJS Crypto Library.

Encryption Key

Hermes requires a key in order to decrypt the configuration file. You can supply this key to Hermes in several ways:

• An environment variable (HERMES_ENCRYPTION_KEY)
  • This option allows Hermes to start as a service without user interaction.
• An interactive CLI program
  • This option requires users to run a CLI command every time hermes restarts, prompting that user for the encryption key. The CLI will send the key to the running Hermes process which can then decrypt the configuration file and continue operation. If the configuration file is encrypted, Hermes will block until it receives the key.

CLI Usage

Encryption

To encrypt the config file, use the following commands:

• Windows: node.exe dist\encryption.js --encrypt
• Linux: node dist/encryption.js --encrypt

When you run this command, it encrypts the configuration file using the provided key (from the HERMES_ENCRYPTION_KEY environment variable or an interactive prompt) and saves the result as production.json.encrypted.

Decryption

To decrypt an encrypted config file, use the following commands:

• Windows: node.exe dist\encryption.js --decrypt
• Linux: node dist/encryption.js --decrypt

When you run this command, it decrypts the configuration file using the provided key (from the HERMES_ENCRYPTION_KEY environment variable or an interactive prompt) and saves the result as production.json.

Provide

To provide the key to the process if installed as a windows service, run the following command:

• node.exe dist\encryption.js --provide

When you run this command, it sends the provided key to the running service, which then decrypts the configuration file in memory without writing it to disk.

SAP Authentication

Hermes connects to SAP using the NetWeaver RFC Software Development Kit (nwrfcsdk). SAP develops and maintains this library, which supports several authentication methods.

Testing Connection

Use the included test script (test.js) to verify the connection between the adapter and SAP. The script calls the STFC_STRUCTURE Remote Function Module.

# Prerequisite: verify that sapnwrfc.ini contains the correct ashost,
# sysnr, client, and credential parameters for your target SAP system.

# Navigate to the Hermes directory and set the RFC library path so
# Node.js can locate the SAP NW RFC shared libraries at runtime:

# macOS — point to the Darwin build of nwrfcsdk:
export DYLD_LIBRARY_PATH=lib/darwin/nwrfcsdk/lib

# Linux — point to the Linux build of nwrfcsdk:
export LD_LIBRARY_PATH=lib/linux/nwrfcsdk/lib

# Windows (Command Prompt) — add nwrfcsdk to PATH:
# set PATH=%PATH%;C:\lib\win32\nwrfcsdk\lib

# Run the test script — it calls STFC_STRUCTURE to validate the connection:
node test

Security and Permissions

A basic overview of Hermes architecture and components is detailed here:

Network

Every minute, Hermes sends HTTPS long-polling requests to the Graphite Public API. In a production environment, ensure Hermes has egress network access to api.graphiteconnect.com.

Hermes connects to SAP over TCP RFC, typically on port 3300. Run Hermes on a system with network access to SAP and the RFC port, as defined in the sapnwrfc.ini file.

Authentication

Hermes reads SAP credentials (username and password) from the sapnwrfc.ini file. SAP defines this file format as the standard configuration method for external programs using the NetWeaver SDK.

Communication

Hermes calls the ABAP remote function module ABAP4_CALL_TRANSACTION, passing a table that contains all vendor information SAP requires. The function module uses the TCODE parameter values XK01, XK02, and XK05 to create, update, and block vendors respectively.