jBASE Agent (jAgent)

jAgent is a server-side jBASE component responsible for accepting and processing incoming client requests.

Communication is established via TCP socket connections and by means of a well defined protocol. jAgent is a
socket server listening on a user-defined TCP port and has the capability to serve a wide range of client
applications as long as they speak the same protocol.

NOTE: This component is only available in jBASE 5.2

This protocol is currently implemented by the following client-side jBASE components:

jBASE jRemote Client API

jBASE JDBC Driver 2.0+
jBASE ODBC Driver

jAgent Administration

Starting jAgent

jAgent may be started from the command line/shell via the following executable:

jbase_agent [<service options>] [<options>]

where the available options are:

-h Show command line help

-p [listenPort] listenPort is the port that will listen for client connections. E.g.

--port=[listenPort] jbase_agent -p 20003

-A [mode] mode is the mode (none | user | account) used to authenticate client connections. E.g.

--authentication=[mode] jbase_agent -A user

-c [path to certificate] path to certificate is the path to a valid x509 certificate.

--certificate=[path to certificate] See also --private_key. This must also be supplied if this option is used. E.g.

jbase_agent --private_key=key.pem --certificate=cert.pem

-k [path to private key] path to private key is the path to a valid private key.

--private_key=[path to private key] See also --certificate. This must also be supplied if this option is used. E.g.
 jbase_agent --private_key=key.pem --certificate=cert.pem
-F Create log files for each client connection (P<pid of connection process>.log
-L [log level] log level is a numeric log level that determines the detail to be logged (default level is
LOG_INFO)
--logLevel=[log level]
0 No logging
1 LOG_TRACE
2 LOG_DEBUG
3 LOG_INFO
4 LOG_NOTICE
5 LOG_WARNING
6 LOG_ERROR
7 LOG_CRITICAL
8 LOG_ALERT
9 LOG_EMERGENCY

Starting jAgent as a Service

The service options allow jAgent to be installed and started as a Win32 Service on Windows platforms, and as a daemon on
Unix platforms.

Windows:

jbase_agent install [-n <Service Name>] <options>

jbase_agent start [-n <Service Name>]
jbase_agent stop [-n <Service Name>]
jbase_agent remove [-n <Service Name>]

or using the jBASE jServControl utility (Note: this utility can only use default values

jServControl install
jServControl start
jServControl stop
jServControl remove
jServControl status

Note that jAgent Win32 services will send logger messages to the Windows Event Log. Changing the tracing level (option –L)
is not applicable to a jAgent service and only error messages will be logged.

Unix:

jbase_agent start <options>

jbase_agent stop

Enabling SSL Encryption

jAgent may be configured to use SSL encryption. To activate SSL encryption it is enough to provide a valid x509 certificate
and a private key (See command line options).

The following example describes how to create a self-signed certificate with OpenSSL:

Create a RSA private key:

C:\programs\openssl\bin>openssl genrsa -out key.pem 1024

Loading 'screen' into random state - done
Generating RSA private key, 1024 bit long modulus
.++++++
....++++++
e is 65537 (0x10001)

Create a certificate (“signing”) request using the previously created private key:
C:\programs\openssl\bin>openssl req -config c:\programs\openssl\openssl.cnf -new -key key.pem
-out req.pem
Loading 'screen' into random state - done
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MyCompanyName
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:MyCompanyName
Email Address []:

Please enter the following 'extra' attributes

to be sent with your certificate request
A challenge password []:
An optional company name []:

At this stage the certificate request should be sent to a Certification Authority, or proceed to the next step to
self-sign the certificate e.g. if used for testing purposes.

Create self-signed certificate:

C:\programs\openssl\bin>openssl req -config c:\programs\openssl\openssl.cnf -x509 -key

key.pem -in req.pem -out cert.pem
-days 365
Loading 'screen' into random state - done

Start jAgent in SSL mode:

C:\programs\openssl\bin>jbase_agent –c cert.pem –k key.pem

Authentication modes:

jAgent supports three different authentication modes (See command line options):

Anonymous authentication does not verify any user credentials

User authentication verifies user credentials against a local user credentials database.
Account authentication will attempt to use the provided user credentials to log into a specific jBASE account.

Setting up User authentication

Create the jAgent user file

$ CREATE-FILE JAGENT_USER 1 53
[ 417 ] File JAGENT_USER]D created , type = J4
[ 417 ] File JAGENT_USER created , type = J4

Create the user and set the password

$ jbase_agent adduser test

$ jbase_agent passwd test newpassword

Now start jbase_agent to authentication with user authentication.

$ jbase_agent -A user

Setting up account authentication

The environment should be configured with JEDIFILENAME_SYSTEM set to a valid jBASE SYSTEM file that
contains the jBASE accounts you wish to connect to.

Start jbase_agent to authentication with account authentication

$ jbase_agent –A account

When using Account authentication, the password used when connecting to jAgent is thge password for the
jBASE account and not the password ofthe connecting user.

Examples:

Starting jAgent on default port (20002):

jbase_agent

Starting jAgent on port 20003 and configure tracing to display errors only

jbase_agent –p 20003 –L 6

Starting jAgent with SSL encryption using certificate mycert.cer and private key mypk.pk

jbase_agent –c c:\certs\mycert.cer –k c:\certs\mypk.pk

Installing and starting jAgent as a Windows Service with default service name (jBASE jAgent Server) on default port

jbase_agent install
jbase_agent start

Installing and starting jAgent as a Windows Service with service name MyAgent1, port 20003, and user authentication

jbase_agent install –n MyjAgent1 –p 20003 –A user

jbase_agent start

Starting jAgent as a Unix daemon on port 20003 and redirecting logging messages to text files.

jbase_agent start –p 20003 -F

Troubleshooting:

Starting jAgent
(5511|46912525605568) ERROR SocketAcceptor: Cannot open port 20002, SocketAcceptor.h +42

jAgent is already running on port 20002. Use a different port number if necessary.

Problems when starting or running jAgent as a Windows Service:

Use the Event log viewer located in the Windows control panel to check for any errors.

Man Page Index