listener.xml

listener.xml is a file where you can define and configure application server instances.

Default configurations

listener.xml is not created by Querix Package Manager.

By default, Lycia comes with two application instances:

• default - requires no authentication. Applications are launched from the user with WebServer is launched. By default, it is the SYSTEM user with and root with ;
• secure - requires authentication. Applications are run from the authorized user.

So, if you do not create your custom listener.xml, Lycia default settings for the application server are:

• default authentication mode – none for default and full for secure
• logging is enabled
• application server instance can be disabled without removing it

• application server working directory (i.e., where programs will be deployed and executed):

  C:\ProgramData\Querix\Lycia\progs
  /opt/Querix/Lycia/progs

• logging directory (i.e., the folder to which log files are saved):

  C:\ProgramData\Querix\Lycia\logs
  /opt/Querix/Lycia/logs

• default location for custom inet.env:

  C:\ProgramData\Querix\Lycia\etc\inet.env
  /opt/Querix/Lycia/etc/inet.env

• default authentication library:

  modauthnt.dll
  modauthcrypt.so, modauthshadow.so, modauthpam.so

How to create your custom listener.xml

If necessary, you can create your custom application server instances. For example, you need several custom application server instances if you use different working directories and different sets of environment variables for different projects.

If yes, you must create custom listener.xml where you will define and configure these custom application server instances.

To create custom listener.xml, please follow these steps:

Step 1. Close LyciaStudio (if necessary).

Step 2. Stop Lycia Web Server.

Step 3. Open your favorite text editor.

Step 4. Copy the template given below to a new text file.

Step 5. Change the template to define your custom application server instance.

Do not forget to copy the whole template – all the tags.

To define your instance, you must set values between the tags.

For example,

...

  <service>
    <name>my_instance</name>
    <applicationdir>C:\my_projects\progs</applicationdir>
    <logdir>C:\my_projects\logs</logdir>
    <envfile>C:\my_projects\my_configs\my_environment</envfile>
    <authmode>full</authmode>
    <auth_module>modauthnt.dll</auth_module>
    <logging>true</logging>
    <description>My custom application server instance</description>
    <enabled>true</enabled>
    <basic_realm>my.domain.name</basic_realm>
    <wait_for_client_to_connect>150</wait_for_client_to_connect>
  </service>

...

Step 6. Name this file listener.xml and save it.

We recommend using these folders to save your custom configuration files:

C:\ProgramData\Querix\Lycia\etc

/opt/Querix/Lycia/etc

If this default folder doesn't suit your development and production needs, you can store your custom configuration files in any other location.

In this case you must add the path to listener.xml as a value of LISTENERXML or LYCIA_CONFIG_PATH environment variables.

If you have only one custom configuration file and it is listener.xml, you may set it in LISTENERXML:

LISTENERXML=C:\my_projects\my_configs\listener.xml

LISTENERXML=opt/my_projects/my_configs/listener.xml

If you have several custom configuration file (including listener.xml), you must set a path to your listener.xml in LYCIA_CONFIG_PATH:

LYCIA_CONFIG_PATH = C:\my_project\configs\

LYCIA_CONFIG_PATH = /opt/my_project/configs/

Step 7. Start Lycia Web Server.

Step 8. Restart LyciaStudio (if necessary).

If you want to keep one or both default application server instances and use them together with your custom ones, you must copy their definition to your custom listener.xml.

Click here to see the definition for two default instances.

<xml>
  <service>
    <name>default</name>
    <applicationdir>C:\ProgramData\Querix\Lycia\progs</applicationdir>
    <logdir>C:\ProgramData\Querix\Lycia\logs</logdir>
    <envfile>C:\ProgramData\Querix\Lycia\etc\inet.env</envfile>
    <authmode>none</authmode>
    <auth_module>modauthnt.dll</auth_module>
    <logging>true</logging>
    <description>Default no authentication listener</description>
    <enabled>true</enabled>
  </service>

  <service>
    <name>secure</name>
    <applicationdir>C:\ProgramData\Querix\Lycia\progs</applicationdir>
    <logdir>C:\ProgramData\Querix\Lycia\logs</logdir>
    <envfile>C:\ProgramData\Querix\Lycia\etc\inet.env</envfile>
    <authmode>full</authmode>
    <auth_module>modauthnt.dll</auth_module>
    <logging>true</logging>
    <description>Default full authentication listener</description>
    <enabled>true</enabled>
    <basic_realm>qx.ua</basic_realm>
  </service>
</xml>

Template for your custom listener.xml

When you define your custom application server instances, you must set values to all the tags:

If necessary, you can copy them from here.

When setting <auth_module></auth_module> for , you can use one or more of the authentication libraries supported by Lycia – modauthcrypt.so, modauthshadow.so, or modauthpam.so.

Tags for defining an application server instance

These are the tags with which define application server instances:

• <service>...</service> – every AppServer instance definition is enclosed in these tags
• <name>...</name> sets the name for the instance - can include Latin letters, arabic numbers (0-9), dashes (-), and underscores (_)
• <applicationdir>...</applicationdir> specifies the application server working directory (i.e., where programs will be deployed and executed)
• <logdir>...</logdir> specifies the folder to which log files will be saved
• <envfile>...</envfile> specifies where inet.env is located
• <authmode>...</authmode> specifies the authentication mode - can be none or full
• <auth_module>...</auth_module> specifies the authentication library
• <logging>...</logging> enables or disables logging - can be true or false
• <description>...</description> holds a short description of the instance
• <enabled>...</enabled> allows disabling the instance without removing it

• <sso>...</sso> switches on the Kerberos protocol for SSO authentication - can be not set, false, or true:

  if not set in listener.xml or set to false, standard authentication procedure will be used;

  if set to true, LyciaWeb will try to go through the SSO authentication (and will ask for standard authentication procedure with entering user name/password only in case SSO authentication fails)

• <basic_realm>...</basic_realm> specifies the name of the domain for which SSO authentication was implemented

• <wait_for_client_to_connect>...</wait_for_client_to_connect> specifies the time (in seconds) during which Lycia WebServer waits for the client to connect (by default, it is 10 s). You can learn about client-server interactions here.

How to manipulate your application server instances

To modify an existing AppServer instance, please follow these steps:

Step 1. Close LyciaStudio (if necessary).

Step 2. Stop Lycia Web Server.

Step 3. Open listener.xml in any text editor.

Step 4. Introduce the necessary changes to one of the existing <service>...</service> blocks.

Step 5. Save the changes.

Step 6. Start Lycia Web Server.

Step 7. Restart LyciaStudio (if necessary).

To delete an existing AppServer instance, please follow these steps:

Step 1. Close LyciaStudio (if necessary).

Step 2. Stop Lycia Web Server.

Step 3. Open listener.xml in any text editor.

Step 4. Select and delete one of the existing <service>...</service> blocks.

Step 5. Save the changes.

Step 6. Start Lycia Web Server.

Step 7. Restart LyciaStudio (if necessary).

How to overwrite default (hardcoded) configurations for Content-Security-Policy directives

The default setting of the directives hardcoded in LyciaWeb.war:

default-src 'self'
script-src 'self' 'unsafe-inline' 'unsafe-eval' https: blob:
img-src * data:
frame-src *
connect-src * data: blob:
style-src * 'unsafe-inline'
media-src *
font-src *

Lycia installation maintainer can configure a global set of CSP directives, by setting custom policy values in:

<xml>
  ...
  <content_security_policy>...</content_security_policy>
  ...
</xml>

The global set above applies to every service in listener.xml.

Related articles

LISTENERXML

LYCIA_CONFIG_PATH

inet.env