Channel history

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

UnrealIRCd 5 supports channel history playback. It has several interfaces for this, the most visible being able to see history-on-join. Note that history playback requires a modern IRC client.

Short guide

To enable this you have to set channel mode +H, type: /MODE #channel +H 15:1440. This will make it remember the last 15 lines for the past 1440 minutes (1 day).

Now, talk in the channel a bit and leave and rejoin the channel. You should see history playback:

Channel history higlighted.png

NOTE: Of course, you must not be the only person in the channel, otherwise the channel will be destroyed when you rejoin.

If you don't see history playback, then check out the client support section.

Ways to retrieve history

In the end there will likely be 3 ways to retrieve history (only #1 and #2 are implemented at this time):

  1. on-join: Automatic history playback whenever you JOIN a channel. The number of lines playback is limited to only the last 15 lines. UnrealIRCd 5.0.0 and later
  2. HISTORY command: Simple command for end-users to retrieve history. Ex: /HISTORY #channel. May provide up to 100 lines. UnrealIRCd 5.0.3 and later
  3. CHATHISTORY (IRCv3): In the future, it is expected that IRCv3 will finalize a specification which will allow IRC clients to fetch channel history dynamically when scrolling. This is expected to be a flexible (and complex) command that will be used by IRC clients only, not by end-users.

In the end, the 3rd interface will give the best results. However, it will take a while until such a specification has been finalized and it will take a lot longer (likely years) until all major IRC clients implement it. In the meantime, #1 is working already for many clients, and end-users can use #2 to see more history if they want to.

Note that all interfaces will always obey channel mode +H. So if +H is not set then you will not be able to retrieve history. If +H is set only allowing 5 lines, then no method can get more than 5 lines. Etc..

Client support

History playback works with modern IRC clients that support the server-time capability. Including:

  • AdiIRC
  • Colloquy
  • HexChat
  • IceChat
  • Konversation
  • KVIrc
  • mIRC: since 7.34 (June 2014)
  • Quassel
  • Textual
  • WeeChat: unfortunately server-time is not enabled by default.
  • Swirc
  • Glirc
  • IRCCloud
  • KiwiIRC
  • The Lounge

If it's not working with any of these clients, make sure you are using their latest version and check the client documentation / client support resources.

Notable clients which do NOT currently support it are:

  • irssi: GitHub issue here, in the meantime consider loading the server_time script via scripts.irssi.org (NOTE: seems to have a conflict with SASL authentication upon server connect)
  • LimeChat
  • Mibbit.

Long guide

To start recording history, set channel mode +H. The syntax is: /MODE #channel +H max-lines-to-record:max-time-to-record-in-minutes.

For example: /MODE #channel +H 50:1440 means the last 50 messages will be stored and no message will be stored longer than 1440 minutes (1 day).

The channel history is then played back when a user joins such a channel. However, the following restrictions apply:

  1. The client must support the 'server-time' CAP ('time' message tag), otherwise history is not shown. Any modern IRC client supports this.
  2. Only a maximum of 15 lines are played back on-join by default

The reason for the maximum 15 lines on-join playback is that this can be quite annoying if you rejoin repeatedly and as to not flood the users screen too much (unwanted).

Since UnrealIRCd 5.0.3 we support history pulling (fetching) via the HISTORY #channel number-of-lines command. It allows you to retrieve up to 100 lines. In the future there will likely be other ways to fetch history as well. In all cases, the maximum number of lines and time configured in the +H channel mode applies, of course, so if your +H setting only allows 20 lines, then you will never be able to fetch more than 20 lines.

You can configure the exact number of lines that are played back and all the limits that apply to +H via set::history::channel.

For saving and retrieving history we currently have the following backend options:

  • history_backend_mem: channel history is stored in memory. This is very fast but also means history is lost on restart.
  • history_backend_null: don't store channel history at all. This can be useful to load on servers with no users on it, such as a hub server, where storing history is unnecessary.

As you can see there is currently no 'disk' backend. However, in the future more options may be added. Also note that 3rd party modules can add history backends as well.