abas Software AG

abas Cloud Connect runs on the customer end of the abas Hybrid Cloud setup and connects the customer’s ERP software to the abas Cloud services.

This setup does not install abas Business Apps or abas BPM.

Installation requirements

Before installing, ensure that all requirements in the following are fulfilled.

Administrative

Hardware

  • At least 4 GB of free RAM are available if you want to connect the ERP client to the cloud. 1 GB of RAM should be calculated for each additional ERP client.

  • At least 10 GB of free disk space is required.

Infrastructure

  • Ensure you have at least 1 Mbit connection per user and a stable ping of 200 ms maximum.

  • The abas Cloud services must be reachable on port 443 via outbound TCP connection from within the company network.

Proxy connections are currently not supported.

Operating system

Before installing, ensure you have the following packages installed:

  • docker engine (version >= 1.17)

  • jq (version >= 1.4)

  • curl, wget, md5sum, base64, python

For security reasons don’t use the root user to run Cloud Connect. For further information see "How to create a Cloud Connect Unix user?".

abas ERP

  • abas ERP ⇒ 2017r4n00, 2017r3n03, 2017r2n07, 2016r4n13 or higher with SSO enabled. (See https://find.abas.de/inno/de/ShowInno.html#query=nummer:20170009)

  • abas ERP EDP port 6550 configured.

  • If you want to configure multiple clients ("mandants"), they must all have a technical user with the same password. This user is used to access abas ERP.

  • Each user currently requires access to the ERP workspace "ow1" (because of the SCREENFETCHER infosystem).

  • postkonfig must be disabled in abas ERP when using user synchronization mode full.

  • The ERP server must be able to communicate with the JWT token validator on the port configured.

Pre-Installation

Create a new Tenant

Please make sure you have an access to the tenant management. For more information see the FAQs: How to login to the tenant management

Request access to the abas Tenant Management Application in the region of your choice from the abas Cloud team:

Please follow the steps below:

  1. First create a new tenant in the abas Tenant Management Web UI (use the red + button in the upper right corner).

  2. Enter the name of the tenant. Use the company name in a company tenant. The field must contain at least 3 characters and allows lowercase letters, numbers and the '-' character. For demo system we suggest usage of the user and the version of the abas ERP installation: maxmu-demo-2017r4.

  3. Assign the tenant to a customer or yourself. The combobox should show you a list of all your customers the abas AG recognizes. If no customers can be selected, there may be a connection failure. Please retry a few minutes later. If the problem persists, please contact us for support.

  4. Please select a tenant type:

    • Self Hosted Instance: For on premise or demosystem installations, which want to use the Cloud services.

    • Managed Instance: For cloud demo abas ERP installations. Use this option, if you want to try out the new webclient or want to present the webclient to customers.

  5. Select Lifetime: After the period of time, the tenant will be deleted automatically. For production purposes, use No Expiration as value.

  6. Select the Auth0 connection type. For details on user synchronization see How does user synchronization work?.

    • Database: Uses a separate user database in auth0.

    • AD/LDAP: Integrates with Active Directory/LDAP through the Active Directory/LDAP Connector that you install in your network. Download link will be provided in the tenant details after the tenant has been created. More information regarding the installation of the AD/LDAP connector can be found here.

    • OAuth2: Uses the OAuth 2.0 protocol.

    • ADFS: Not yet supported automatically. Contact abas for more support.

  7. The administrator email will be prefilled with your email address.

  8. Click Save.

The creation of Self Hosted Instances will take 1-2 Minutes. For Managed Instances the creation takes about 20 minutes.

Create your configuration token

An email is sent when the creation of your tenant was successful and is ready to be used. Then you can create a configuration token for your tenant:

  • Go to your tenant’s management UI (e.g. https://manage.abas.cloud).

  • Click on your tenant in the tenant list. This will guide you to the details page.

  • There you find a button named "Create new configuration".

  • Click this button and copy the contents to your clipboard, or somewhere secure. You will need this during the setup procedure.

Create Tenant Managers

The tenant managers are users which can manage a given tenant. Per default only the tenant owner is a manager. In this case he is the only one who can manage the given tenant. For that reason we recommend you to add more managers per tenant.

To add a new tenant manager, select the given tenant click on Managers. On the top of the table write the email address of the new manager and click on the check button on the right of the field. If the manager is not accepted, it is due to either one or a combination of the following reasons:

  • The provided email adress is invalid

  • The user has no access to the tenant management

  • The user has never logged in to the tenant management.

For more information see the FAQs: Cannot login to the tenant management?

Set up hybrid tenant

This step is not necessary for Managed instances.

Create new user

  1. Create a new user using the following command: useradd -m cloud-connect

  2. Add the user to the docker group: usermod -a -G docker cloud-connect

  3. Switch to the newly created user: su - cloud-connect

  4. Create a keypair for the user name. Use an empty password: ssh-keygen -t rsa

  5. Authorize the user cloud-connect to log in as <s3-user>@<erp-server> by using his SSH identity: ssh-copy-id <s3-user>@<erp-server>. If ssh-copy-id is not available in your system, you can copy the ssh identity manually into the authorized_keys of the s3 user.

Install cloud Connect

You can download abas Cloud Connect when you hybrid tenant has been created.

Let’s assume your tenant’s name is "cloud-demo" and it has been created in the US region. You can download the abas Cloud Connect package here:

for the EU region, you can download here:

Before you continue to install abas Cloud Connect, read the requirements (see below).

Download abas Cloud Connect, extract it and start the installation procedure in the current directory of your Linux workstation as follows:

(wget -qO- 'https://cloud-demo.abas.cloud/cloud-connect.tgz' | tar xfz -) && ./setup.sh

This downloads the package, extracts it in the current directory (/u/cloud-connect/) and not in a subfolder. The script will immediately start the setup procedure.

The script ./setup.sh will guide you through the setup procedure. Basically, it generates a configuration file. Advanced users may amend the file configuration.json directly for detailed configuration. Invoke ./setup.sh and follow the instructions. This script amends the following for each ERP client:

  • It sets up the abas REST API.

  • It generates a new SSO configuration and License Controller settings for abas ERP ($MANDANTDIR/.server.conf).

  • It installs an ESDK application which contains an infosystem that serves the Web UI screen definitions (ow1/SCREENFETCHER).

  • It installs and starts a dedicated instance of the abas full text search.

  • It installs and configures a new full text search index called "quicksearch" for the Web UI.

  • It adds a cron job to fill the full text search index.

Make sure you keep cloud connect up to date. (See How to update cloud connect)

Hybrid instance in licensing mode

Installation process

In order to simplify or automate the licensing of abas products, abas ERP from version 2018r4n14p10 contains the technical requirements for licensing via the central abas License Server. The use of the abas License Server is

  • optional for the operation of abas ERP version 2018r4n14 and

  • prerequisite for the operation of abas ERP as of version 2019.

Furthermore, the use of the abas License Server is a prerequisite for the licensing and use of ESDK Apps.

Cloud Connect can be installed in two modes:

  • Licensing Only Mode : Installs only the License Controller. The use of the abas Web Client in the hybrid operating model or the use of other abas Cloud Services is not possible in this case. Access to abas ERP from outside is also not possible.

  • Cloud Connect Mode : Installs all infrastructure components required for hybrid operation as well as the License Controller. In Cloud Connect Mode, a secure, bidirectional connection via Internet from the internal network to the abas Cloud is established via an outbound port. This enables, for example, the use of the abas Web Client in the hybrid operating model or the use of other abas Cloud Services.

Installation Number Configuration

After the installation process and running the software is completed, all you need is to provide the installation number into .server.conf.

Cloud Connect will add to each client the .server.conf file which has the following structure:

[LicenseController]
url = http://<license-controller-host>:8912
installation = <instNum>

Please add the installation number, the URL will be provided by Cloud Connect during the installation process.

The file .server.conf has the following priority:

  1. $MANDANTDIR/.server.conf

  2. $HOMEDIR/.server.conf

  3. /etc/abas/server.conf (without . at the beginning of the file)

In case you have only one installation number for all clients, please copy $MANDANTDIR/.server.conf to $HOMEDIR/.server.conf and set the installation number in $HOMEDIR/.server.conf.

In case you have multiple production clients, which have different installation numbers and run in the same s3 environment, please fill the installation numbers into the $MANDANTDIR/.server.conf.

FAQs

Q: What happens if I upgrade to 2018r4n14p10 and don’t install the License Controller?

A: abas ERP will continue working as before. 

Q: I installed the License Controller, but the installation number in .server.conf is not set. What happens?

A: In this case abas ERP will continue working as before. No benefit of the License Server.

Q: I’m not using the License Controller. How will licensing of abas ERP be handled in this situation?

A: The licensing will be handled manually as usual.

Q: How long is the license over the license controller valid?

A: The license is valid for 60 days. The License Controller checks multiple times a day for a new license and syncs the licenses.

Q: I ordered new licenses and the license controller is installed. How can I receive them?

A: The license syncing is being triggered automatically every 6 hours. If you want to retrieve the license immediately, just run the liz program. A dialog will appear "If you continue, your abas ERP license will be updated." Click YES. This will trigger the syncing.

Q: What happens, if the license controller has no internet access

A: The licenses are valid for 60 days. abas ERP will continue working for another 32 days. 4 weeks before the license expiration, abas ERP will notify, that the license will expire in 28 days.

Q: What if the customer is unable to provide an internet connection for more than 2 months?

A: In this case we can provide a manual licensing. 

Q: I have an installation with multiple clients, which I want to split. What to do?

A: You can split the clients into multiple s3 installations. You need to configure the .server.conf to point to the same license controller and set the right installation number.

Q: What do I need to do, when I create a new client from an existing one using mandcopy.sh

A: If the license controller is configured over $HOMEDIR, then you don’t need to do any changes. If the configuration is in $MANDANTDIR, you need to copy .server.conf and set the proper installation number.

Q: Is it possible to use the License Controller for two installations?

A: If you use Cloud Connect in Licensing only mode, then you can use the License Controller for multiple abas ERP installations. Please note, that they need to belong to the same customer.

Running the software

When the setup is complete, run the software. Run the script ./run.sh. It downloads and starts the following docker containers:

  1. Token validator (for the JWT validation in the abas REST API and the ERP)

  2. The abas Client Agent

  3. The abas REST API

  4. Cloud Watch Agent

The configuration in detail

The configuration file

The ./setup.sh script generates an initial configuration file named configuration.json. To do this, manually copy the file configuration.json.template and make your changes. It is important to fill in the required user name and password properties. The section services.erp should also be adjusted to suit your setup.

{
    "tenant": "",                   # Enter your tenant's name here
    "domain": "eu.abas.cloud",      # Set this to the domain name assigned to you by abas
    "aws_access_key_id": "",        # Set this to the access key id provided by abas
    "aws_secret_access_key": "",    # Set this to the secret key provided by abas
    "options": {
        "dockerRegistry": {
            "username":"",          # Set the docker registry user name or leave it empty for interactive login
            "password":""           # Set the docker registry password or leave it empty for interactive login
        },
        "esdkInstaller": {
            "username":"",          # Set the user name for basic auth to access https://registry.abas.sh or leave it empty for interactive login
            "password":""           # Set the password for basic auth to access https://registry.abas.sh or leave it empty for interactive login
        },
        "useSSH": true,
        "awslogsEnabled": true    # Upload log files in ./logs to the abas cloud to help with troubleshooting
    },
    "apps": {
        "screenFetcher": {
            "install": true,
            "generate_all_screens": false
        }
    },
    "services": {
        "environment": {            # Persistent environment variables
        },
        "erp": {
            "host": "localhost",    # Change this to the host on which abas ERP runs
            "port": 6550,           # This is the EDP port
            "user": null,           # If the technical ERP user for Cloud Connect needs a user name, enter it here
            "ssh": {
                "user": "s3",       # Change this to a valid SSH user for the ERP workstation (needs passwordless login)
                "port": 22          # The SSH port
            }
        }
    }
}

Extend the configuration with environment variables

Multiple environment variables are involved in starting Cloud Connect. In the environment section of the configuration.json file you can store values for environment during start-up. Example of configuring available heap memory and enabling JMX access to the REST API:

$ cat configuration.json
{
    "tenant": "test",
    "domain": "eu.abas.cloud",
...
    "services": {
        "environment": {
          "MW_JVM_OPTS": "-Xmx4g -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9011 -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false"
        },
...
    }
}

Change docker compose settings using docker compose overrides

For example, if you need to change the default networking properties of docker compose, you may use an additional custom docker compose file. The name of the file must be docker-compose-custom.yml. If the file exists, it will automatically be picked up during the startup and will extend and/or override the default docker compose file. Continuing with the JMX example, here are the contents of an example file to expose the JMX port locally on a random port:

$ cat docker-compose-custom.yml
version: "2.2"
services:
  rest-api:
    ports:
      - 127.0.0.1::9011

Extend the abas REST API configuration

The abas REST API is a Spring Boot application. To customize the settings and make them persistent (update-safe), create the file ./mw/abasconfig/application-custom.properties. The properties you set there will override the default properties in ./mw/abasconfig/application.properties.

Disable the Cloud Connect full text search for a client

The Cloud Connect full text search is used in the abas Web UI to search for abas objects. The full text search can be disabled, if you don’t wish to use it for single or multiple clients (e.g. too much disk space, you need to copy the clients using mandcopy.sh, etc.), by creating the following file:

$NOBACKUP/cloudsearch/$MNAME/disabled

If this file exists the run.sh command will not start the FTS web server (jetty) for this mandant. The cron job which is responsible for updating the index will also stop running until you remove this file.

FAQs

How to update cloud connect

You can update cloud-connect simply by calling run.sh:

./run.sh

We strongly recommend you to create a nightly cron job and keep cloud connect always up to date. For example, a nightly execution at 23:45 can be scheduled with the following cron table entry:

45 23 * * * /home/cloud-connect/run.sh

The job can be scheduled manually with crontab -e, or automatically, with the following command:

(crontab -l 2>/dev/null; echo "45 23 * * * /home/cloud-connect/run.sh ") | crontab -

How to avoid auto-update? Important note for preparing a customer demonstration.

Cloud Connect updates itself on startup. The following steps are required to ensure the update is not activated during a presentation:

Before the presentation

Make sure you have the latest cloud connect installed. (see How to update cloud connect)

During the presentation

If you must call run.sh, add a parameter to skip the automatic update:

./run.sh --do-not-update

Always note that you require a stable and fast internet connection.

What information should we include in a request for support?

If log collection was enabled, we only require the tenant name (e.g. "mytenant.eu.abas.cloud"). Otherwise, we may need access to your logs. In which case you must zip the "./logs/" directory

zip -r cloud-connect-logs.zip ./logs/ VERSION

and provide us with that archive (cloud-connect-logs.zip).

How does user synchronization work?

If you get the error message invalid token, it is usually due to the problem that Cloud Connect can’t find a password record in abas ERP. The password record is searched using the field ssologinname and is required for Cloud Connect to function.

Cloud Connect ensures that the field ssologinname is filled correctly with the abas Cloud user ID in the password record. The synchronization for the abas Cloud user you are logged in with, takes place after using the Web UI for the first time. Cloud Connect synchronizes abas Cloud users in abas ERP in 2 ways:

Update only

Password records will be updated if the following applies:

  • Check if there is a password record for $,ssologinname==${abas_cloud_user_id} and if not,

  • Check if there is a password record for $,pemail==${email}.

  • If such a password record exists, we will update it and set the abas Cloud user ID.

Full

  • A password record which acts as a template user will be created.
    On startup, Cloud Connect searches for a template user where the field ssologinname is set to {unixname} (ERP Query $,ssologinname=={unixname}).
    If this template user doesn’t exist, it will be created and used as a template for all other password records that will be created by Cloud Connect.

  • If no matching password record exists, it will be copied and created from the template user, with the abas Cloud user ID set correctly.

  • Requirements: The configuration contains a reference to abas Essentials "workspace" and a "permissions" record. These records must exist so that the template user can be created successfully.

What are the minimal permissions for the Cloud Connect ERP user?

The following ERP permissions are currently required:

  • Default workspaces and the custom workspace "ow1"

  • Additionally, the following database permissions are required:

Table 1. Database permissions
Database Group Permissions Notes

Company (12)

Configuration (18)

view, select

Company (12)

Password (11)

view, select, update, new, copy

"new" and "copy" are only required for UserSyncMode==full. The priority for this must be at least as high as the highest priority of all Cloud users. Otherwise, changes must be made manually.

Infosystem (65)

Infosystem (1)

view, select, update, new

Only if the Web UI is used (import of the ScreenFetcher infosystem)

Permission (85)

Permission (1)

view, select, update, new

Needed by ESDK

Permission (85)

Workspace (2)

view, select, update, new

Needed by ESDK

PrintParameter (88)

<all groups>

view, select, update, new

Only if the Web UI is used (import of the ScreenFetcher infosystem)

How to create a Cloud Connect user?

Migration from root user

Please create a new Cloud Connect user. When the user has been created, stop abas Cloud Connect and:

  1. Using the following command, change the ownership of the folder where abas Cloud Connect has been installed:
    sudo chown -R cloud-connect <path-to-cloud-connect>

  2. Copy the content of the folder to /u/cloud-connect/

  3. Log in as a Cloud Connect user with su - cloud-connect

  4. Start run.sh with ./run.sh

If you have configured an init.d script, please ensure you have amended the script to the new path of abas Cloud Connect and you start the run.sh using the Cloud Connect user and not the root user.

How to set up multiple Cloud Connect installations on the same workstation?

If you want to install Cloud Connect multiple times on the same workstation, you must ensure that they don’t use the same ports. Currently, the only ports which are exposed are from the token validator and from the license controller.

Please ensure that the jwt and the license controller in configuration.json are assigned different ports per installation.

    "services": {
        ...
        "jwt": {
            "port": 19950,
            ...
        },
        "license_server": {
            "port": 8912
        },
        ...
    }

Multiple Cloud Connect installations are supported, but not for the same ERP client (mandant).

Docker uses the same network range. How can I change it?

We provide custom endpoints where you can change the docker compose files. Those changes are not affected after an update of cloud connect. Please create the following files in the cloud-connect folder installation and restart cloud-connect.

docker-compose-custom.yml

version: '2.2'
networks:
  default:
    driver: bridge
    ipam:
      config:
      - subnet:  10.103.1.1/24

docker-compose-license-controller.yml

version: '2.2'
networks:
  default:
    driver: bridge
    ipam:
      config:
      - subnet:  10.103.0.1/24
Please make sure that by configuring the subnets, there is no overlap in the ip ranges

How do tenant incident alarms work?

If we detect a connectivity problem with a hybrid tenant we will send an alarm email to the tenant managers.

We continuously monitor the health of the connection between the on-premise installation and the Cloud. If more than 40% of these health checks fail over a period of 15 minutes, an email is sent. E.g.:

  • All health checks fail because there is a complete outage. The threshold is reached after 6 minutes at which point the alarm is activated.

  • Half of the health checks fail because there are connectivity problems. In that case it would take 12 minutes for the alarm to be activated.

We enable these emails by default. If your tenant is disconnected on a regular basis (e.g. a presentation system that is only started when required) you may wish to not receive the emails for this tenant. This can be configured on the "Tenant managers" page of your tenant.

Cannot login to the tenant management?

Before you sign in, please synchronize your data with the abas extranet: Synchronize