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]

--port=[listenPort]

 listenPort is the port that will listen for client connections. E.g.

jbase_agent -p 20003
-A [mode]

--authentication=[mode]

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

jbase_agent -A user
-c [path to certificate]

--certificate=[path to certificate]

 path to certificate is the path to a valid x509 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]

--private_key=[path to private key]

 path to private key is the path to a valid 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]

--logLevel=[log level]

 log level is a numeric log level that determines the detail to be logged (default level is LOG_INFO)

 

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.

 

1.       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.

 

                       

2.       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:

 

1.       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)

 

2.       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.

 

1.    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

 

2.       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):

 

1.    Anonymous authentication does not verify any user credentials

2.    User authentication verifies user credentials against a local user credentials database.

3.    Account authentication will attempt to use the provided user credentials to log into a specific jBASE account.

 

Setting up User authentication

 

1.       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

 

2.       Create the user and set the password

 

$  jbase_agent adduser test

$  jbase_agent passwd test newpassword

 

3.       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.

 

1.    Start jbase_agent to authentication with account authentication

 

$ jbase_agent –A account

 

 

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:

 

1.       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.

 

 

2.    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