. . .

FAQ

This list of FAQs contains common questions and problems during installation on various platforms. In most cases the logs tell what is going wrong if something is not working as expected:


Where can I find detailed logs?

Linux

  • MongoDB: As provided with the logpath key in the mongodb config

  • Dashboard: /opt/aom-dashboard/site/apiomat/log/application.log

  • YAMBAS: /var/log/aom-yambas/

Windows

  • MongoDB: As provided with the logpath key in the mongodb config

  • The locations of the other logfiles are linked in one single place: C:\Program Files\ApiOmat\logs. The links go to:

    • C:\tomcat8\logs ("CONSOLE" appender / standard output logs here)

    • C:\Users\YourUser\AppData\Local\ApiOmat\logs ("FILE" appender logs here)

    • C:\Apache24\logs

    • C:\Apache24\htdocs\dashboard\apiomat\log

  • To read the logs in a continuous way (show new lines automatically), use the PowerShell cmdlet Get-Content with the "-wait" parameter

    • For example: gc .\catalina.out -tail 100 -wait

YAMBAS startup setups with error message "license server not available"

This commonly occurs when the installation hosts traffic is can not connect to the license server. Please ask support for a offline license key and provide the hardware ID printed out during startup of YAMBAS in tomcat logs.

Dashboard login does not work, no incoming request is logged on YAMBAS

Please check your hostname settings in yambas.conf and try to run a curl command against the hostname, as shown

cURL

curl http://localhost:8080/yambas/rest

Images are not properly displayed in Dashboard, what should I do?

Please see "Dashboard login does not work, no incoming request is logged on YAMBAS"

The error "AH02018: request body exceeds maximum size (xxxxx) for SSL buffer" appears

Go to your SSL configuration and adjust <Location /dashboard>:

dashboard

SSLRenegBufferSize 10486000

SSL certificate problem: unable to get local issuer certificate' in /opt/aom-dashboard/site/apiomat/protected/extensions/EActiveResource/EActiveResourceRequest.php:542

Please check your certificates. The error "unable to get local issuer certificate" indicates that the CA-certificate (or one of the certs in the chain) couldn't be verified. Try to investigate the error with the command:

Command

openssl s_client -connect host:port

With this command you can take a closer look for the problem. The problem should be that the CA-certificate is missing on the server system. Download the correct CA-certificate file (the output of the command should tell you which one you'll need) from the homepage of your CA and add it to /usr/local/share/ca-certificates and then run

Command

sudo update-ca-certificates

error:140770FC:SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol

Please check your yambas.host configuration in the yambas.conf. Can you reach the specified server with curl on the command line? The error indicates that you're trying to connect to a wrong port (most common: you're trying to establish a HTTPS connection on the HTTP-Port)

cURL

curl https://localhost:8443/yambas/rest

SSL certificate problem: unable to upload/download native module via ANT because of "javax.net.ssl.SSLProtocolException: handshake alert: unrecognized_name"

The server alias in your apache conf has a different value than your ssl certificate.

Please change the "ServerAlias" value in your apache conf to the name that is set in the ssl certificate.

403 during yum or apt update

Please check your package manager. Are the packages sources mirrored? Have our installation packages have been added? You can ask the admin or the data center.

Internal Server Error SSL received a record that exceeded the maximum permissible length.

Try the following: Disable useSsl in yambas.conf (useSsl=false)

All users can read the data of other users. Is this a security hole?

No. 1) This only applies to the basics.User class with the default module configuration. 2) You can either create a subclass and modify the access rules, or change the configuration of the module "Basics" accordingly (see Basics Module).


I forgot the SuperAdmin password, but cannot use the password reset function (e.g. no E-Mail-Host is configured). How can I reset the password?

It is possible to hash a new password and set it directly to database. Follow these instructions to reset SuperAdmin password on database layer:

  1. Ensure ApiOmat Yambas is running

  2. Extract the configEncryption key from your apiomat.yaml and use it as pepper, e.g.: pepper=4FhnGPU6WfwP9rJ1X1htuTyj2dRNuaQ8

  3. Open a connection to your MongoDb

  4. Navigate to the collection apiomat.Customer and select the customer with _id=SuperAdmin (e.g. via mongo shell db.Customer.find({_id:"SuperAdmin"}) )

  5. Extract the value of the json key 'salt' from response, e.g. salt=75b1620333c34606623a9b6789589c98fff268c966591310072ad1503401a0ba

  6. Create a new password, e.g. password=123456

  7. Hash your password manually using the following settings: PBKDF2 With Hmac SHA512 , 4 iterations, key length 256, salt and peppered password

Java

import javax.crypto.SecretKey;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.PBEKeySpec;
import javax.xml.bind.DatatypeConverter;
public class PasswordHasher
{
public static void main( String[ ] args ) throws Exception
{
/* values from example above */
final String salt = "75b1620333c34606623a9b6789589c98fff268c966591310072ad1503401a0ba";
final String pepper = "4FhnGPU6WfwP9rJ1X1htuTyj2dRNuaQ8";
final String password = "secret";
 
final String hashedPassword = createShaHash( pepper, salt, password ).toLowerCase( );
System.out.println( hashedPassword );
}
 
private static String createShaHash( String pepper, String salt, String password ) throws Exception
{
final int iterations = 4;
final int keyLength = 256;
final String keyAlgorithm = "PBKDF2WithHmacSHA512";
 
final SecretKeyFactory skf = SecretKeyFactory.getInstance( keyAlgorithm );
final PBEKeySpec spec =
new PBEKeySpec( ( pepper + password ).toCharArray( ), salt.getBytes( ), iterations, keyLength );
final SecretKey key = skf.generateSecret( spec );
final byte[ ] data = key.getEncoded( );
return DatatypeConverter.printHexBinary( data );
}
}

8. Copy the generated lower case hash and paste it to apiomat.Customer.SuperAdmin.password, e.g. password=801843d2b43936173f16ec6531adada9d0194719b938a260d6f25861a36f5068 (backing up the old password is recommended!)
9. Restart your yambas to clean the customer cache and login with your new password

CentOS 7.5.X php70w-pear package error

How to solve following error:

Error: Package: apiomat-dashboard-3.2.1-0.x86_64 (apiomat)
Requires: php70w-pear
Available: 1:php70w-pear-1.10.4-1.w7.noarch (webtatic)
php70w-pear = 1:1.10.4-1.w7


First try to remove all php packages.


Command

sudo yum remove php*

Try to install the package manually


Command

curl -O https://centos.pkgs.org/7/webtatic-x86_64/php70w-pear-1.10.4-1.w7.noarch.rpm.html
sudo yum localinstall php70w-pear-1.10.4-1.w7.noarch.rpm

Finally the problem should be solved.


I want my Yambas instance to be connected to more than one Docker network. How can I do that?

Using docker-compose it's generally possible to configure the compose file so that Yambas is connected to more than one network. However, there are certain issues you might run into when starting Yambas that way regarding the communication with Hazelcast and Consul. We will discuss them here with a simple example.

Let's say you added some custom networks to your compose file and configured the Yambas service to connect to all of them.

Example compose file with three networks defined
version: '2.4'
services:
...
yambas:
...
networks:
net1:
priority: 1000
net2:
...
net3:
...
...
networks:
net1:
...
net2:
...
net3:
...

With this configuration, the container will try to connect to each network in the order defined by the given priority. So in this example the container will try to connect to net1 first. You may have noticed the version at the top being set to '2.4'. That is because in version 3 the feature for passing priorities to network connections isn't implemented at the moment. Before Yambas itself starts, Hazelcast interface and Consul health check host are set. Without further configuration, if connected to multiple networks the container will use the first IP address found which in this case should come from net1 as it should have been connected to first. We suggest to only set a priority on the network that should be connected to first and don't pass any priorities to the other networks (0 will then be used as a default). If Hazelcast and Consul are also connected to net1, everything should be fine. If a connection between Yambas and the two mentioned services still can't be established or if they're only connected to net2 and/or net3, further configuration is necessary.

To let Yambas know specifically which IP address should be used by Hazelcast, the PREFERRED_HAZELCAST_INTERFACE_HOST environment variable must be set accordingly. Same goes for Consul with PREFERRED_CONSUL_HEALTH_CHECK_HOST.

Below you can see the adjusted network configuration in our example compose file. In order to make this work, the IP addresses Yambas will use on the respective networks must be preconfigured. Suppose Hazelcast is only connected to net2 and Consul is only connected to net3.

Configuration that tells Yambas exactly which IPs to give to Hazelcast and Consul
version: '2.4'
services:
...
yambas:
...
environment:
PREFERRED_HAZELCAST_INTERFACE_HOST: 172.20.0.3
PREFERRED_CONSUL_HEALTH_CHECK_HOST: 172.21.0.3
networks:
net1:
# With both environment variables defined above, this priority may also be left out, 
# for example if you'd like to use compose version 3 (which we recommend) instead of 2.4.
priority: 1000
net2:
# Hazelcast is connected to this network
ipv4_address: 172.20.0.3
net3:
# Consul is connected to this network
ipv4_address: 172.21.0.3
...
networks:
net1:
...
net2:
...
net3:
...

This way regardless of the network priorities Yambas container will have the correct addresses set for both services.

If you don't care which host addresses are used you can simply leave out the according environment variables as well as the network priorities.