Using ZNC and soju with onekeyirc

onekeyirc-ircnow-bouncer-guide.txt

Entering commands correctly

Commands beginning with "onekeyirc" run in your operating system's shell. Commands beginning with "/" run inside onekeyirc.

Inside onekeyirc, press "/" from the live log or a command response reader. This opens Command with a slash already entered. Type the remainder of the command and press Enter.

For example, to run:

/znc ListNetworks press "/", then type:

znc ListNetworks When pasting, open Command first, omit the initial slash, and paste one command at a time. Pasting directly into the live log opens Compose, where the pasted text is treated as a chat message.

Gather your bouncer details You need:

Bouncer type: ZNC or soju. Bouncer hostname and assigned TLS port. Bouncer account username and password. The exact network name configured on the bouncer. Your IRC nickname. An optional stable client name, such as "laptop". Use the bouncer's hostname in the server field. The bouncer separately connects to the upstream IRC network.

IRCNow's ZNC examples use TLS port 31337. Use the port assigned to your account; other installations may use something different.

Configure the profile If onekeyirc is already running, use that session. Otherwise, start it from your shell:

onekeyirc --reconnect Then open:

/panel At "Choose a panel", choose the numbered server profile. On a fresh setup, this is normally:

1: (not configured) Number 0 is Application preferences. Choose a server number for bouncer setup.

For ZNC, the relevant fields look like this:

Server: bouncer.example.org Use TLS: yes Port: 31337 Nickname: mynick Connection type: znc Bouncer username: myaccount Bouncer network: ircnow Bouncer client name: laptop Apply automatic away: no Replace the example hostname, nickname, account, and network with your actual values.

For soju, choose:

Connection type: soju and use its assigned hostname and TLS port.

Enter the bouncer username, network, and client name separately. Do not include "/" or "@" separators in those individual fields. The client constructs the login identity.

Keep the client name stable across reconnects. A different device can use a different name for separate playback tracking when supported by the bouncer.

Set "Auto-connect at startup" to "yes" if this profile should connect whenever a new onekeyirc process starts.

Supply only the bouncer password The panel offers three password sources:

"plain": Hidden entry, saved as plaintext in the private configuration file. "file": An existing private plaintext file containing the password. "gpg": An existing encrypted password file, or creation of one using an existing local public key. In each case, supply only the bouncer password.

For ZNC, onekeyirc constructs:

myaccount@laptop/ircnow:password Without a client name, it constructs:

myaccount/ircnow:password Do not enter that combined string yourself when using the dedicated ZNC mode.

For soju, onekeyirc constructs the SASL identity:

myaccount/ircnow@laptop and supplies the password separately. The soju profile requires successful SASL PLAIN authentication over verified TLS.

Your bouncer password and the upstream network's NickServ or SASL password have different jobs. Configure the upstream authentication in the bouncer.

For password files, use a regular file owned by your Unix account with mode 0600 or 0400. GPG credentials must be decryptable without an interactive prompt when the client connects.

Finish and connect The server panel's final choices are:

1 Save and connect 2 Save only 3 Connect once 4 Apply without saving Choose 1 to save and connect. The default is 2, which saves without connecting.

If you are editing an already connected profile, choose Save only. Then select that profile and reconnect explicitly:

/servers /server 1 /disconnect /connect Use the actual server number. Saving changes does not replace a live connection's settings, and an automatic reconnect continues using the interrupted connection's existing settings.

Use the bouncer controls Select the intended profile first:

/servers /server 1 For ZNC:

/znc asks ZNC for help.

/znc ListNetworks lists its configured networks.

/znc Connect asks ZNC to connect its selected upstream network when that network is disconnected.

For soju:

/soju asks BouncerServ for help.

/soju network status lists the bouncer's networks and their status. The latter is also documented in the current soju manual.

To read bouncer replies, open the selected server's message view:

/server There are two separate connection operations to remember:

"/connect" connects onekeyirc to the bouncer. "/znc Connect" asks ZNC to connect to its upstream IRC network. Channels and additional networks After login, the bouncer restores its current channel memberships.

List and select channels with:

/channels /channel #example To join a channel:

/join #example To leave it:

/part #example An ordinary PART changes the bouncer's membership and can stop further collection in that channel. Leave channels joined if you want the bouncer to keep collecting their messages.

In bouncer mode, onekeyirc does not replay its saved auto-join list. This avoids rejoining a channel that you deliberately left from another device.

For another upstream network, create another profile:

/server add bouncer.example.org 31337 mynick /servers The add command creates a profile without selecting, connecting, or saving it. Open "/panel", choose the new profile number, and configure its bouncer type and network name.

Use one profile per upstream network. When several profiles share a hostname, select the intended profile by number and then use bare "/connect":

/server 2 /connect Playback, catch-up, and away state The bouncer decides which retained messages to send when you connect. onekeyirc displays valid original server timestamps in UTC and handles recognized history batches as replay.

From the live log:

Page Up browses older retained messages. Home reaches the oldest retained page. End returns to the live tail. Within a channel or private conversation:

/catchup starts from your most recent locally sent message when that anchor remains available in the current session's eligible log or retained memory. It does not request an archive from the bouncer.

For the usual multi-device setup, leave "Apply automatic away" set to "no". Manual away commands remain available:

/away Away for a while /back Leave the terminal and return later To keep the local onekeyirc session running while releasing the terminal:

/background Later, from a shell under the same Unix account:

onekeyirc --sessions onekeyirc --resume 1 Use the job number reported by "--sessions". That number is separate from an in-program server number and from an operating system PID.

If an old SSH terminal still owns the job:

onekeyirc --detach-session 1 onekeyirc --resume 1 Detaching preserves the running worker, connections, drafts, and retained history.

"/quit" or "--close-session" ends the local client job. It does not stop the remote bouncer daemon. The bouncer's upstream connection and history retention follow its own settings.

For a fresh unattended launch, save "Auto-connect at startup: yes" for the desired profiles, then run:

onekeyirc --background --reconnect "--background" does not enable autoconnect by itself. A background worker must also remain alive to be resumed; it cannot survive a reboot or client crash.

The complete posting file adds both manual configuration examples and troubleshooting for login failures, missing channels, TLS errors, unapplied settings, and busy sessions.

[1] Implementation reference: onekeyirc-0.1.30-source.tar.gz , particularly MANUAL.txt, doc/BOUNCERS.txt, doc/SESSION-CONTROLS.txt, and the setup and command handlers.

onekeyirc can connect to an IRC bouncer using dedicated ZNC or soju profiles. The bouncer maintains its own connection to IRC and can send retained messages when the client reconnects.

This guide describes onekeyirc 0.1.30. Check your installed version from the shell:

onekeyirc --version

See the general onekeyirc page for the client overview.

Entering the commands in this guide

Commands starting with onekeyirc belong in your operating system's shell. Commands starting with / belong in onekeyirc's Command screen.

For each slash command, press / from the live log or a command response reader, enter the rest of the command after the slash already displayed, then press Enter. For example, press /, type znc ListNetworks, and press Enter.

When pasting, open Command first, omit the initial slash, and paste one command at a time. Check that the screen says Command. Pasting directly into the live log opens Compose, where a slash is ordinary message text.

Before connecting

Have these details ready:

  • Bouncer type: ZNC or soju.
  • The bouncer hostname and assigned TLS port.
  • Your bouncer account username and password.
  • The exact name of a network configured on that bouncer.
  • Your IRC nickname.
  • An optional stable client name, such as laptop or desktop.

The server field takes the bouncer's hostname. The bouncer separately connects to the upstream IRC server.

IRCNow's ZNC connection examples use TLS port 31337. Use the port supplied for your account; another provider or a soju installation may use a different port. Enter the hostname without https://, a path, or a port suffix.

The bouncer account, the network name stored by the bouncer, and your IRC nickname are separate values. A network named ircnow is not necessarily named after its upstream hostname.

Obtain the account and configure its upstream network through your provider or the bouncer's administration tools before following this connection procedure.

Set up a bouncer profile

If onekeyirc is already running, use that session. Otherwise start it from the shell:

onekeyirc --reconnect

The --reconnect option retries temporary connection failures. It does not create an account or configure the bouncer.

Inside onekeyirc, open:

/panel

At "Choose a panel", choose the numbered server profile you want to configure. On a fresh setup this is normally 1: (not configured). Number 0 is Application preferences, so choose a server number for bouncer setup.

If an existing profile should be kept, create an additional profile using the "More than one network" section below.

Connection fields

For a ZNC example, enter these values, replacing every example account and address:

Server:                 bouncer.example.org
Use TLS:                yes
Port:                   31337
Nickname:               mynick
Connection type:        znc
Bouncer username:       myaccount
Bouncer network:        ircnow
Bouncer client name:    laptop
Apply automatic away:   no

For soju, choose soju as Connection type and use its assigned hostname and TLS port. The remaining bouncer identity fields have the same purpose.

Enter the username, network and client name separately. These fields accept up to 63 ASCII letters, digits, dots, underscores and hyphens each. Do not put / or @ separators into them. The client name is optional; - clears it.

Keep a client name stable across reconnects. Use a different name for another device if you want separate per-client playback tracking and your bouncer supports it.

"IRC username" is the ordinary IRC USER field. Put the bouncer login account in "Bouncer username".

Set "Auto-connect at startup" to yes if this profile should connect whenever a new onekeyirc process starts. Choose no for manual connection.

Keep "Apply automatic away" at no for the usual multi-device setup. This lets the bouncer coordinate automatic away state instead of allowing one idle client to mark the shared presence away.

Bouncer password

At "Bouncer password source", choose one of:

  • plain: enter the password in a hidden field. Saving the profile stores it as plaintext in the private configuration file.
  • file: use an existing private plaintext file containing only the password.
  • gpg: use an existing GPG-encrypted password file, or choose create to make one with an existing local public key.

Supply only the bouncer account password.

For ZNC, onekeyirc constructs the login in this form:

myaccount@laptop/ircnow:password

Without a client name, it constructs:

myaccount/ircnow:password

Do not enter either combined string in the dedicated password field.

For soju, onekeyirc constructs the SASL identity:

myaccount/ircnow@laptop

Without a client name, the identity is myaccount/ircnow. The password is supplied separately. This mode requires successful SASL PLAIN authentication over verified TLS.

The bouncer password is separate from any NickServ or SASL password used by the bouncer on its upstream network. Configure upstream authentication in the bouncer.

For file or gpg, use a file owned by your Unix account with permissions 0600 or 0400. Credential symlinks are refused. A private directory with permissions 0700 is appropriate for the configuration and credential files.

The panel stores credential paths as absolute paths. GPG "create" asks for the full fingerprint of an existing local public key and asks for the password twice. The matching private key must be usable without an interactive prompt when onekeyirc later connects.

Finish and connect

Press Enter to keep a displayed setting. Use - to clear an optional field. At optional new mention or ignore entries, an empty answer finishes the list. For help about a question, press Tab to select its heading, then ?.

At Finish, review the hostname, network, login identity and password source. Choose:

  • 1 Save and connect to save the profile and start a connection.
  • 2 Save only to save without connecting. This is the default.
  • 3 Connect once to apply and connect without saving.
  • 4 Apply without saving to apply without saving or connecting.

Earlier answers do not save settings or start a connection.

If the profile is already connected, choose Save only. Select that profile afterward, then explicitly disconnect and reconnect to use changed connection settings:

/servers
/server 1
/disconnect
/connect

Replace 1 with the intended server number. Saving does not change a live connection, and an automatic retry continues with that connection's existing settings.

Changing an endpoint, bouncer identity or CA selection clears the old password source in the setup draft. Supply the password source for the new settings before finishing.

Use /panel for bouncers. The shorter /quickstart flow is for direct IRC connections.

Check the connection and use the bouncer controls

Commands operate on the selected server profile. To choose a profile:

/servers
/server 1

Replace 1 with its listed server number. If you chose Save only and it is disconnected, connect using:

/connect

Use bare /connect after selecting the profile, especially when several profiles share the same bouncer hostname.

ZNC

Ask ZNC for its own command help:

/znc

List the networks in your ZNC account:

/znc ListNetworks

If you have logged into ZNC but it reports that the selected upstream network is disconnected, ask ZNC to connect it:

/znc Connect

The last command concerns ZNC's connection to the IRC network. A plain /connect concerns onekeyirc's connection to the bouncer.

For an enabled ZNC module, use its actual module name:

/msg *module COMMAND

Replace module and COMMAND with the module and command you intend to use. Available modules and permissions depend on the bouncer.

soju

Ask BouncerServ for help:

/soju

List saved networks and their status:

/soju network status

Use the service's help for further network and account management. The /soju shortcut sends commands to BouncerServ; it does not create a network merely by being enabled in a client profile.

Reading replies

Open the selected server's message view:

/server

The no-argument form selects the server view. It does not create another connection.

The matching /znc or /soju shortcut requires a connected profile of that type. Bouncer controls are sent as single messages and are excluded from onekeyirc's input history and local message echoes. Service replies appear in the server view and are excluded from its optional persistent logs. Text can still be visible while you compose it, and the bouncer has its own logging policy.

Channels and membership

The bouncer restores the channels it is already joined to. List and select them with:

/channels
/channel #example

Selecting a channel changes the displayed conversation. To actually join a channel:

/join #example

To leave a channel deliberately:

/part #example

Replace #example with the desired channel. An ordinary PART leaves that channel through the bouncer and can stop further collection there. To keep collecting messages while you are away, leave the channel joined.

In bouncer mode, onekeyirc does not replay its saved auto-join list. The bouncer's current membership is authoritative, which avoids rejoining channels you left from another device.

/autojoin explains the policy; its add, remove and clear operations are refused for a bouncer profile. Explicit startup commands can still run, so review any configured startup JOINs or service commands.

More than one network

Use one onekeyirc server profile per upstream network, even when the profiles share a bouncer hostname, account and port.

To add another profile without connecting immediately:

/server add bouncer.example.org 31337 mynick
/servers

Replace the hostname, port and nickname first. The add command creates a profile but does not select, connect or save it.

Open /panel, choose the new profile's number, and complete its bouncer settings. Give it the other network's exact name. Choose Save and connect when it is ready.

Select the intended profile before using its bouncer commands:

/server 2
/znc ListNetworks

This example assumes the new profile is number 2 and uses ZNC. Use the actual number and the matching command for its bouncer type.

onekeyirc does not automatically discover every network or create a local profile for each one. /servers lists local server profiles; /znc ListNetworks and /soju network status ask the remote bouncer about its networks.

Playback and local history

After login, the bouncer may push retained channel and private messages. What is available depends on its retention settings and the client identity used.

onekeyirc displays valid original server timestamps in UTC. Recognized historical batches are handled as replay: they do not generate fresh mention alerts, execute CTCP or DCC requests, or overwrite current channel membership and presence.

Scrollback is bounded. From the live log, Page Up browses older retained messages, Home reaches the oldest retained page, and End returns to the live tail.

In a channel or private conversation:

/catchup

starts from your most recent locally sent message when its anchor is available in the current session's eligible log or retained memory. It does not ask the bouncer to retrieve an archive.

A new process does not restore its previous in-memory session from old transcript files. onekeyirc also does not provide an on-demand bouncer archive browser or promise duplicate-free replay across fresh processes. Older bouncers that do not identify history batches cannot provide the same replay boundary.

Away state

By default, bouncer profiles suppress onekeyirc's automatic idle/background-away behavior. Manual controls still work:

/away Away for a while
/back

Enable "Apply automatic away" in that profile's panel only if you want it to follow onekeyirc's existing idle/background-away preferences. Another device or the bouncer itself can also change the account's away state.

Leave the terminal and return later

The remote bouncer and the local onekeyirc process have separate lifetimes.

To keep the current onekeyirc process, its connections and retained history running while releasing the terminal, enter:

/background

Later, from the shell under the same Unix account:

onekeyirc --sessions
onekeyirc --resume 1

Use the job number reported by --sessions. It is not a PID and is separate from an in-program server number.

If a lost SSH terminal still owns the job and resume reports it busy:

onekeyirc --detach-session 1
onekeyirc --resume 1

Detaching releases the old terminal while retaining the running worker. A worker must already be managed, through /background or --background, before you rely on this recovery.

/quit and onekeyirc --close-session 1 end the local client job and all of its connections. They do not stop the remote bouncer daemon. Its upstream connection and retention continue according to its own settings.

A reboot or client crash ends the local worker; it cannot be resumed afterward.

Starting an unattended client

For a fresh background launch, first save "Auto-connect at startup: yes" on every profile that should connect. Then, when the desired worker is not already running, use:

onekeyirc --background --reconnect

--background creates the background job; it does not enable autoconnect by itself. --reconnect handles temporary connection failures. Use --sessions and --resume to inspect the result.

A locked GPG key cannot open an interactive password prompt during unattended startup. Check that the chosen credential source works in that environment.

The bouncer can remain connected to IRC even when onekeyirc is stopped. Running onekeyirc in the background is useful when you also want to retain the local client session.

Optional: configure a profile by editing a file

The panel is sufficient for setup. These alternatives show the corresponding configuration keys for manual editing.

Use a separate configuration file for the chosen example. Replace the hostname, port, nickname, account, network and credential path. The encrypted file must already exist and contain only the bouncer password.

ZNC example

[connection]
server=bouncer.example.org
port=31337
tls=true
nick=mynick
autoconnect=false
auth=none
server_password_gpg_file=/home/me/.config/onekeyirc/credentials/bouncer.gpg

[bouncer]
type=znc
username=myaccount
network=ircnow
client=laptop
automatic_away=false

soju example

[connection]
server=bouncer.example.org
port=6697
tls=true
nick=mynick
autoconnect=false
auth=sasl
password_gpg_file=/home/me/.config/onekeyirc/credentials/bouncer.gpg

[bouncer]
type=soju
username=myaccount
network=ircnow
client=laptop
automatic_away=false

The port 6697 in the soju example is illustrative; use your provider's assigned TLS port.

Leave auth_user empty in either explicit bouncer mode. ZNC requires auth=none and a server-password source. soju requires auth=sasl and an authentication-password source.

Choose exactly one source for the applicable password. For ZNC the alternatives are server_password_file, server_password_gpg_file or server_password. For soju they are password_file, password_gpg_file or password.

Use absolute file paths. Values are literal: ~ and shell variables are not expanded inside the configuration. Keep the configuration private, normally mode 0600 in a directory owned by you with mode 0700.

Check the chosen file from the shell, substituting its actual path:

onekeyirc --config /home/me/.config/onekeyirc/bouncer.ini --check-config
onekeyirc --config /home/me/.config/onekeyirc/bouncer.ini --reconnect

The examples disable startup autoconnect, so use /connect inside the launched client. The configuration check validates syntax and option combinations; it does not test password access, GPG decryption, TLS or a real login.

When converting an old manually combined ZNC password to explicit type=znc, change its stored credential to contain only the password. Otherwise the client would add the identity to an already combined value.

Troubleshooting

Unknown /znc, /soju or bouncer settings

Check onekeyirc --version and /help bouncers. This guide was checked against 0.1.30. Installing a newer executable does not replace code already loaded by a running background worker; deliberately restart that worker after upgrading.

Authentication fails

Check the selected bouncer type, account, exact network name and password source. Supply only the bouncer password. soju must offer SASL PLAIN and accept the login.

Use:

/autoauth status
/server

to inspect configured credential locations and server diagnostics. /autoauth status does not print password contents. Edit bouncer credentials through /panel.

TLS verification fails

Check the assigned hostname and port, the system clock, and the CA trust store. Keep TLS verification enabled. The client-to-bouncer TLS settings and the bouncer-to-network TLS settings are separate.

Connected, but no channels or backlog

Select the intended local profile and inspect /server. Ask the bouncer for network status. Confirm that the upstream network is connected and that the bouncer is joined to the desired channels.

Backlog depends on retention and playback settings. A client name identifies a playback consumer; changing it may change what the bouncer considers already delivered.

Saved changes seem ignored

Choose the correct profile, then explicitly /disconnect and /connect. Saving and automatic retry do not replace an active connection's settings.

Resume is busy or lists no jobs

Run the session commands under the account that owns the client. For a busy managed job, use --detach-session before --resume. A stopped worker or a process that never became managed has no resumable session.

Further reading

Inside onekeyirc:

/help bouncers
/help panel
/help sessions
/help authentication
/help tls

The 0.1.30 source archive includes MANUAL.txt, doc/BOUNCERS.txt, doc/SESSION-CONTROLS.txt, examples/bouncer-znc.ini and examples/bouncer-soju.ini.