The first time the web server is started, an empty IRC server list will be created automatically as "servers.json" in the base folder of the repository.
Upon the first login to the web page at `/irc/webclient.html`, the browser will automatically display the Server List editor form panel. Required fields are marked with a colored dot. The IRC server edit form includes detail instructions for each input field using help [?] buttons at each input field.
There are two ways to edit the list of IRC server definitions, using the browser web page or use of a text editor to modify the configuration file directly. This first section will focus on the use of the web page editor. The second section at the bottom of this page includes instructions related to the manual edit method.
It is also possible to globally disable the web page server list editor by setting "disableServerListEditor:true" in the credentials.json file or setting the environment variable "IRC_DISABLE_LIST_EDITOR=true" This may be useful if the IRC client is to be restricted to one IRC network. In the case where the editor has been disabled, the manual edit method must be used.
The irc-hybrid-client supports multiple concurrent web browsers to be connected at the same time. This creates a possible conflict if changes to the server list on one device are not propagated properly to other devices currently logged into the web page.
Therefore, it is necessary to disconnect from the IRC network in order to make changes to any IRC server definition. The IRC Server List may be opened at any time, even if connected to IRC, but the buttons used to invoke the editor will be disabled on hidden in the server list table.
Similarly, if a user decides to manually edit the servers.json file in the base folder of the repository without protections of the web page, it would be recommended to stop the node server during manual edit of server.json.
Starting in Version v2.0.0, the server list panel and the server list editor form are integral to the application.
From the application's dropdown navigation menu in the upper left of the page, the IRC Server List can be invoked from the "View Panels...", "IRC Server List" selection in the dropdown navigation menu.
The IRC Server List can be invoked at any time using the Alt-L (List) HotKey.
From the IRC Controls panel, the server list can be invoked using the [Show IRC Server List] button.
At the bottom of the panel, the [Edit Selected Server] button will directly invoke the editor panel without requiring the Server List panel to be opened.
The IRC Server List web page will present the current list of IRC server definitions in table format. The list is loaded from the servers.json file in the base folder of the web server. The column labeled "Index" indicates the server index position in the list. The server definition with the lowest index number that is not disabled will be the default definition that will be selected when backend web server is started.
The disable checkbox is used to prevent an individual IRC server definition from being selected. Disabled IRC server definitions are excluded from automatic server rotation when connections fail. The disabled checkbox is the only property that may be modified from within in the server list table.
The "group" column shows an integer group number. Groups are used to configure and define a common group of IRC server definitions. In the event of an IRC server network connection failures, different IRC servers within a common group number can be automatically rotated to other servers in the group. Group 0 is reserved for stand alone servers. A rotation group is defined when the group number is 1 or greater . If more than two server in a group are not disabled and both have the reconnect property enabled, then upon disconnect, the client will automatically rotate IRC server definitions within a server group.
The [Select] button can be used to set one row of the table as the currently selected server. The cell of the table for the select buttons and connect buttons will be color highlighted. Red background indicated the selected server is disconnected from IRC. Green color indicated the server is connected to the IRC network.
The [Connect] button submits a request to the web server to initiate a new IRC connection. While connected, this button on the server list table may be used to disconnect from IRC.
The [Edit] button will open IRC Server edit form as shown below in the next section.
The [Duplicate] button will duplicate the associated IRC server definition and insert the copy immediately after the source IRC server in the server list.
The [Delete] button will remove the associated IRC server from the list.
At the top of the panel, the [Create New IRC Server] button will open the Server Edit form populated with some default values.
When connected to the IRC network, buttons related to edit functions are hidden or disabled.
The section of the Server List panel marked "Set Table Width" contains 3 buttons used to view alternate configuration of the server list table.
The button marked [Default] will display the table as shown above, with editing buttons visible. This is the primary format for most situations.
The button marked [Show All Columns] is intended to reveal all of the columns of the table. In order to fit this table into a reasonable width, the functional buttons are not included in this format. (Note the Show All Columns screen capture just below is scaled to about 64 percent of original size)
The button marked [Thin Mobile] is intended for an iPhone display in vertical orientation. This is intended to allow Select or Connect to a specific server in the Server List. To edit the server list it would be necessary to use the Default display width and scroll or rotate the display. Since settings are shared with multiple devices, IRC Server List may be modified using a laptop or desktop, then used in a mobile smartphone.
Data is entered into a simple HTML form. After editing is complete, the [Save] button will write the changes to the database file on the web server. The [Cancel] button will leave the data unchanged.
The disable/hide checkbox is used to prevent an individual server from being selected.
The "Server Rotation Group Number" field shows an integer group number. Groups are used to configure and define a common group of IRC server definitions. In the event of IRC server network connection failures, different IRC servers within a common group number can be automatically rotated to other servers in the group. Group 0 is reserved for stand alone servers. A rotation group is defined when the group number is 1 or greater . If more than two server in a group are not disabled and both have the Auto Reconnect property enabled, then upon disconnect, the client will automatically rotate IRC server definitions within a server group.
The "Label" is used to provide a descriptive name for an IRC server definition. The Label is not otherwise used, and it may contain any arbitrary string values. If you are using a small screen smartphone, it is best to keep the Label short.
When the Automatic-Reconnect checkbox is checked, after disconnect, the IRC client will attempt to reconnect to IRC. For the first try, it will use the existing server definition and existing nickname. In the case where first reconnect attempt using the same IRC server and nickname fails, if additional IRC servers have been defined within a Group, other IRC server definitions will be tried. Upon reconnect, it will attempt to re-join up to 5 channels that were open at the time of disconnection. This feature does not support channel passwords.
At this time there are no provisions to configure a server to auto-connect to IRC on startup. There is no provision to auto-join channels on startup
When the Log IRC checkbox is checked, the raw IRC messages from the IRC server are written the file "irc.log" located in the logs folder. Caution should be used as logging of passwords or other bot credentials may occur. Some filters are included to redact common password syntax before writing to the log, but the list may not include all possibilities. This is really intended for debugging. There are obvious privacy concerns here. It is recommended to leave this set to false.
The IRC server address, port, and TLS settings are similar to other IRC clients.
The checkbox for Use Socks5 Proxy will enable this IRC server definition to use the programs global socks5 configuration for the IRC connection. This setting is ignored when socks5 proxy is disabled or has not been configured in the web server settings. Socks5 settings must be configured globally in the credentials.json file or with environment variables in the .env file as described in the login config section.
If IRC server password field is optional. It may used for IRC servers that require a password in order to connect to the IRC network. The password is a write-only field and the current value may not be viewed from the web page for security reasons. Security note: The IRC server password is stored in plain text in the servers.json file, and it may be viewed there.
SASL authorization is optional. IRC server SASL authorization was added specifically for use with libera.chat and has not been tested on any other IRC networks. If both SASL username and password contain valid string values, the SASL username and SASL password will be sent to the IRC server during the initial connection. To disable, leave these values blank. In the event of a login failure, a standard IRC connection will be attempted without SASL. The only mechanism supported at this time is PLAIN. The SASL password is a write-only field and the current value may not be viewed from the web page for security reasons. Security note: The SASL password is stored in plain text in the servers.json file, and it may be viewed there.
The IRC nickname, real name, used ID and initial modes are similar to other IRC clients.
If an optional Alternate Nickname is specified, it will be tried when the primary nickname is not available. If the nickname recovery checkbox is checked, should the primary nickname become available while the user is logged in to IRC with the alternate nickname, automatic recovery of the primary nickname will be attempted. The manual configuration section shown below provides a detailed explanation of nickname recovery.
The IRC channel list is a comma separated list of channel names. In the client interface, a button will be created for each channel to /JOIN the channel when pressed.
The IRC services section is optional. Leave these field empty to disable this feature. The purpose is to send a user IDENTIFY message to a NickServ service. The command may contain passwords so it is a write-only value and the command may not be viewed from the web page. The command is stored in the servers.json files on the web server in plain text format. The manual configuration section shown below provides a detailed explanation and example for services configuration.
After edit is complete, use the [Save] button. The [Cancel] button will discard changes and close the panel.
For purposes of this help file, it is assumed the person manually configuring the IRC server list is familiar with standard IRC server connection parameters, including hostname or IP address, port number, TLS flag, IRC nickname, IRC user, and real name. If you are not familiar with these concepts, it is recommended to consult some general IRC help web pages.
A brief note about syntax. The servers.json file represents a JSON structured data object. JSON syntax must be exact. The servers.json file includes a "serverArray" property. The square brackets [ ] define a javascript array.
"serverArray": [ ]
Each of the curley braces { } within the array is a javascript object with one object for each server definition. Note the server objects are separated by commas, except the last server.
"serverArray": [ { ...the first server... }, { ...the second server... }, { ...the third server... } ]
Server Configuration (each IRC server)
The "disabled" property is used to prevent an individual server from being selected.
The "group" property contains an integer group number. Groups are used to configure and define a common group of IRC server definitions. Different IRC servers can be rotated after disconnect from the IRC network. Group 0 is reserved for stand alone servers. In the case where the group number is 1 or greater a rotation group is defined. If more than 2 server in a group are not disabled and have reconnect enabled, then up on disconnect the client will automatically rotate IRC server definitions within a server group.
The "name" property is used to provide a descriptive name for an IRC server definition. The value is not otherwise used, and it may contain any arbitrary string values. If you are using a smartphone, it is best to keep the name short.
"disabled": false, "group": 0, "name": "DALnet",
There are 5 properties to define an IRC server entry.
At this time there are no provisions to configure a server to auto-connect to IRC on startup. There is no provision to auto-join channels on startup.
In this example, an IRC server is configured without TLS encryption.
"host": "lion.dal.net", "port": 6667, "tls": false, "verify": false, "password": "",
To configure for TLS encryption the "port" was changed to 6697 and "tls" was set to true. If the IRC server hostname should be verified, set "verify" to true. For number IP addresses, set "verify" to false.
"host": "lion.dal.net", "port": 6697, "tls": true, "verify": true, "password": "",
Security note: The optional IRC server password will be stored unencrypted in clear text in the servers.json file. It is recommended to check for proper file permissions.
IRC server SASL authorization was added specifically for use with libera.chat and has not been tested on any other IRC networks. If both SASL username and password contain valid string values, the SASL username and SASL password will be sent to the IRC server during the initial connection. To disable, leave these values blank. In the event of a login failure, a standard IRC connection will be attempted without SASL. The only mechanism supported at this time is PLAIN.
"saslUsername": "", "saslPassword": "",
Security note: The optional SASL password will be stored unencrypted in clear text in the servers.json file. It is recommended to check for proper file permissions.
When the "proxy" property is set to true, the IRC client will attempt to connect to IRC using the Socks5 proxy configuration that was defined globally in the credentials.json file or environment variables. This is described in the login config page of the documentation. If the socks5 proxy is disabled globally, the proxy property is ignored.
When the "reconnect" property is set to true, after disconnect, the IRC client will attempt to reconnect to IRC. For the first try, it will use the existing server definition and existing nickname. In the case where first reconnect attempt using the same IRC server and nickname fails, if additional IRC servers have been defined within a Group, other IRC server definitions will be tried. Upon reconnect, it will attempt to re-join up to 5 channels that were open at the time of disconnection. This feature does not support channel passwords.
When the "logging" property is set to true, IRC messages are written to the "logs/irc.log" file located with the backend web server. There are no provisions for logging on the local machine where the web browser is open. All messages from the IRC server are logged in raw message format. The program does not include log file pruning, so please watch the size of your log files as they can become quite large. Caution should be used as logging of passwords or other bot credentials may occur. This is really intended for debugging. It is recommended to leave this set to false.
"proxy": false, "reconnect": true, "logging": true,
This input values in this section with nickname, user name, and real name should be obvious to anyone familiar with using IRC.
The "altNick" field is used when the primary nickname is unavailable. When "recoverNick" is set to true, automatic recovery of the primary nickname will be attempted when the primary nickname becomes available.
In the case where an IRC server returns a 433 ERR_NICKNAMEINUSE prior to nickname registration, the altNick value will be submitted as an alternate nickname. If recoverNick is set to true, the automatic nickname recovery process will be activated by the 433 message. The "nickRecoveryActive" property in the irc state object will be set to true so the web browser can update status icons accordingly.
In the case where an IRC server returns a 432 ERR_ERRONEUSNICKNAME prior to nickname registration, the altNick value will be submitted as an alternate nickname. However, auto-recovery of the primary nickname is not enabled. This is because 432 is probably caused by a services/nickserv nickname lock, and manual user intervention will most likely be needed to clear the 432 IRC server message.
Upon IRC disconnect, if the alternate nickname is in use at the time of disconnect, the requested nickname will revert back to the primary nickname value. Next next connection event will therefore use the primary nickname. If the use has entered an ad-hoc nickname value different from both the primary and alternate nicknames, the ad-hoc nickname will persist after disconnect.
As a special case for DALnet where the user's nickname may be forced to a value of "Guest12345" by services/nickserv. The numeric part shown here as 12345 is uniquely created and may be a different number. Unless the user's primary nickname has been set to Guest12345 in the configuration, the Guest* nickname will revert to the primary nickname after IRC server disconnect.
If recoverNick is set to the true, the client will automatically attempt to recover the primary nickname by sending a NICK command with the primary nickname. This is triggered in 2 ways. If a ghost user with primary nickname is present in an IRC channel with the active alternate nickname, a QUIT message will trigger immediate nickname recovery. Otherwise, a cycle timer will periodically attempt to send NICK commands with the primary nickname until a time limit is reached. The duration between attempts increases over time.
The automatic recovery of a nickname can be cancelled at any time by using the /NICK command to change nicknames.
Please note that different types of IRC servers have different requirements for the number of characters allowed in a Nickname, user or real name. These are often displayed in a server message when you first connect to IRC. At the present time, the maximum length of these values is not checked by this program, so exceeding the limit set by the server would generate an IRC server error.
"nick": "MyNickname", "altNick": "", "recoverNick", false, "user": "user", "real": "John Doe", "modes": "+i",
At this time, the program does not auto-join of IRC #channels on startup. This may be added in the future.
The "channelList" property is used to designate a javascript array of string entries, where each array value is the name of an IRC channel. After connection to an IRC server, the favorite channels are displayed as buttons to allow easy /JOIN capability when using a smartphone. The array may be empty, but it must exist.
If the IRC server auto-reconnect is enabled as discussed below, then upon a successful re-connect to the irc server, up to 5 irc channels will be automatically rejoined. The IRC channels eligible to be automatically rejoined is based on channels open at the time of disconnect. Automatic rejoin of channels has no relationship to the defined channelList array.
"channelList": ["#myChannel", "#otherChannel"],
There is a provision to automatically dispatch a NickServ IDENTIFY message. This enabled when the IRC configured primary nickname matches the property "identifyNick" and both identifyNick and identifyCommand properties are strings of length greater than zero. This feature is disabled by clearing either or both of the properties.
Triggers:
- Prior to nickname registration, the nickserv IDENTIFY command is triggered upon receiving an IRC server "001" RPL_WELCOME message.
- During nickname recovery, the nickserv IDENTIFY command is triggered upon server "NICK" message with proper nickname values.
Security Note: the optional identify command may contain passwords. This configuration is stored unencrypted in clear text in the servers.json file. It is recommended to check for proper file permissions.
To disable this feature, set the following properties to be zero length strings.
"identifyNick": "", "identifyCommand": "",
Please read this section carefully. This "identifyCommand" property
represents a
If NickServ services requires a simple private message then the PRIVMSG raw server command would be used. The format of the entire message starts with the command "PRIVMSG", followed by a space, followed by the IRC nickname of the recipient, followed by a space. The the message delimiter is a colon character ":" which is then followed with the private message contents. To identify in this manner using the password xxxxxxxx to identify your nickname MyNickname, the configuration would be set as shown in the next example. Note the colon character prefixing :IDENTIFY
"identifyNick": "MyNickname", "identifyCommand": "PRIVMSG NickServ :IDENTIFY xxxxxxxx",
In the case where services have non-spoofable nicknames, the recipient of the private message would be modified as shown in the next example. Note the colon character prefixing :IDENTIFY
"identifyNick": "MyNickname", "identifyCommand": "PRIVMSG NickServ@services.dal.net :IDENTIFY xxxxxxxx",
In the case where an IRC network has reserved "NICKSERV" as a custom IRC command you can use the next method. It reduces the risk of sending your IDENTIFY password to another user pretending to be nickserv. In this case, IDENTIFY and the password are sent as command parameters, so the colon is not required.
"identifyNick": "MyNickname", "identifyCommand": "NICKSERV IDENTIFY xxxxxxxx",
Global Configuration
The property "configVersion" is intended to throw a JavaScript error on the NodeJs web server when the format version does not match the expected value. The expected value is currently 2.
Upgrade Notes: For upgrade from 0.1.44 to 0.2.x perform the following changes:
- Set property "configVersion" to 2
- Remove property ircAutoReconnect (if you don't, the property is ignored)
- Remove property rawMessageLog (if you don't, the property is ignored)
- For each server definition, 4 new properties are required: disabled, proxy, reconnect, and logging. The simplest way to do this is to open each server using the server list editor web page to review each server definition, then save the entry. Alternately, the properties can be added manually to the servers.json file.
The "ctcpTimeLocale" property is optional. It may be used to specify a CTCP TIME reply format. It may be used in the case where a client time zone when different from the server. This is used by native JavaScript toLocaleString() function. Caution, the toLocaleString() is implementation dependant, and this was written using Debian 10. The value is an array. The first element is the toLocaleString() locales string. The default locales string is "en.US". The second element is used by the timeZone property of toLocaleString options parameter. The default value is "UTC". It may be set to a different locale value such as "America/Chicago".
Example server.json
The server.json file should look something like this.
{
"configVersion": 2,
"ctcpTimeLocale": ["en-US", "UTC"],
"serverArray": [
{
"disabled": false,
"group": 0,
"name": "DALnet",
"host": "lion.dal.net",
"port": 6697,
"tls": true,
"verify": true,
"proxy": false,
"reconnect": false,
"logging": false,
"password": "",
"saslUsername": "",
"saslPassword": "",
"identifyNick": "MyNickname",
"identifyCommand": "PRIVMSG NickServ@services.dal.net :IDENTIFY xxxxxxxx",
"nick": "MyNickname",
"altNick": "",
"recoverNick", false,
"user": "user",
"real": "John Doe",
"modes": "+i",
"channelList": ["#myChannel", "#otherChannel"]
}
]
}