listener.xml

listener.xml is a file where you can define and configure application server instances. By default, the listener.xml file is not created by Querix Package Manager. Create one to store non-default configurations.

Default Configurations

By default, Lycia comes with two application instances:

• default - requires no authentication. Applications are launched under the user by which the WebServer has been launched. By default, it is the SYSTEM user on Windows and root user on Linux/UNIX;
• secure - requires authentication. Applications are run from the authorized user.

Default instances have the following parameters:

With no 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 (that is, 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.soC

Custom listener.xml

You may need several custom application server instances - for example, if you intend to use different working directories and different sets of environment variables for different projects. Configure these custom application server instances in you listener.xml file.

To create custom listener.xml, follow these steps:

Step 1. Stop Lycia Web Server;

Step 2. In your VS Code's Workspace area, open the etc folder within the LYCIADIR. By default, the paths should be:

• /opt/Querix/Lycia/etc (on Linux/UNIX);
• C:\ProgramData\Querix\Lycia\etc (on Windows).

Step 3. Create a new file with the name listener.xml, and press Enter.

We recommend using the default folder listed in Step 2 to save your custom configuration files.

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 the path in LISTENERXML:

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

LISTENERXML=opt/my_projects/my_configs/listener.xml

If you have several custom configuration files (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/

The file will open in the Editor area;

Step 4. Copy the template given below to this file;

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

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>
    <wait_for_client_to_connect>150</wait_for_client_to_connect>
  </service>

...

Step 7. Start Lycia Web Server.

Template for a Custom listener.xml

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

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 that 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;

• <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: Client-Server Interactions.

  <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);

Optional tags:

• <cookie_attributes ... /> defines the cookie attributes;
• <content_security_policy>...</content_security_policy> defines the content security directives;
• <html_lang>...</html_lang> specifies the language of the HTML page.

Cookie Attributes

You can configure the attributes of cookies in listener.xml file. You can set any combination of these attributes in the <cookie_attributes> tag and it is up to web browser to accept or decline resulting cookies.

If they are not configured, the default behaviour is:

• For secure scheme (application URL starts with https://) cookie attributes are set as follows: http-only=”yes”, secure="yes", same-site=”none”;

• For non-secure scheme (application URL starts with http://) cookie attributes are set as follows: http-only not set, secure not set, same-site=”Lax”.

The configuration is the following: set cookie attribute values in the cookie_attributes tag. Example:

<cookie_attributes http-only=”true” secure=”true” same-site=”None” />

Attribute names are case-sensitive (lowercased). Attribute values are case-insensitive (Lax and lax are equivalent, Yes and yes too).

Content Security Policy

The content security policies are specified withing the <content_security_policy> tag:

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

The default set of the directives, hardcoded in LyciaWeb.war:

Should you need to set other values, set custom policy values in:

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

HTML Page Language

For a generated HTML page at a program runtime, you can specify the page language for the purpose of better accessibility within the tag <html_lang> in the following format: <language[_country]>. For example, for the German language and Germany, add the following:

Managing Application Server Instances

To modify an existing AppServer instance, follow these steps:

Step 1.Stop Lycia Web Server.

Step 2. Open listener.xml in your VS Code instance and add necessary changes to one of the existing <service>...</service> blocks.

Step 3.Start Lycia Web Server.

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

Step 1.Stop Lycia Web Server.

Step 2. Open listener.xml in your VS Code instance.

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

Step 4. Start Lycia Web Server.

Related articles

LISTENERXML

LYCIA_CONFIG_PATH

inet.env