From e4df6a7c53ab6e9dd6d63516ca9e0ad143cfa17a Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Thu, 29 Jul 2021 21:10:10 +0000 Subject: Add latest changes from gitlab-org/gitlab@master --- doc/user/project/integrations/irker.md | 94 +++++++++++++++++++--------------- 1 file changed, 53 insertions(+), 41 deletions(-) (limited to 'doc/user/project/integrations/irker.md') diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 295300fb55d..79df556ac8f 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,57 +4,69 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Irker IRC Gateway **(FREE)** +# irker IRC Gateway **(FREE)** -GitLab provides a way to push update messages to an Irker server. When +GitLab provides a way to push update messages to an irker server. When configured, pushes to a project trigger the service to send data directly -to the Irker server. +to the irker server. -See the [project homepage](https://gitlab.com/esr/irker) for further information. +See also the [irker integration API documentation](../../../api/services.md). -## Needed setup +For more information, see the [irker project homepage](https://gitlab.com/esr/irker). -You first need an Irker daemon. You can download the Irker code -[from its repository](https://gitlab.com/esr/irker): +## Set up an irker daemon -```shell -git clone https://gitlab.com/esr/irker.git -``` +You need to set up an irker daemon. To do so: -Once you have downloaded the code, you can run the Python script named `irkerd`. -This script is the gateway script, it acts both as an IRC client, for sending -messages to an IRC server, and as a TCP server, for receiving messages -from the GitLab service. +1. Download the irker code [from its repository](https://gitlab.com/esr/irker): -If the Irker server runs on the same machine, you are done. If not, you + ```shell + git clone https://gitlab.com/esr/irker.git + ``` + +1. Run the Python script named `irkerd`. This is the gateway script. + It acts both as an IRC client, for sending messages to an IRC server, + and as a TCP server, for receiving messages from the GitLab service. + +If the irker server runs on the same machine, you are done. If not, you need to follow the first steps of the next section. +WARNING: +irker does **not** have built-in authentication, which makes it vulnerable to spamming IRC channels if +it is hosted outside of a firewall. To prevent abuse, make sure you run the daemon on a secured +network. For more details, read +[Security analysis of irker](http://www.catb.org/~esr/irker/security.html). + ## Complete these steps in GitLab -1. Navigate to the project you want to configure for notifications. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click "Irker". +1. On the top bar, select **Menu > Projects** and find the project you want to + configure for notifications. +1. Navigate to the [Integrations page](overview.md#accessing-integrations). +1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. -1. Enter the server host address where `irkerd` runs (defaults to `localhost`) - in the `Server host` field on the Web page -1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the - `Server port` field on the Web page. -1. Optional: if `Default IRC URI` is set, it has to be in the format - `irc[s]://domain.name` and is prepended to each and every channel provided - by the user which is not a full URI. -1. Specify the recipients (e.g. #channel1, user1, etc.) -1. Save or optionally click "Test Settings". - -## Note on Irker recipients - -Irker accepts channel names of the form `chan` and `#chan`, both for the -`#chan` channel. If you want to send messages in query, you need to add -`,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter -case, `Aorimn` is treated as a nick and no more as a channel name. - -Irker can also join password-protected channels. Users need to append -`?key=thesecretpassword` to the channel name. When using this feature remember to -**not** put the `#` sign in front of the channel name; failing to do so -results in Irker joining a channel literally named `#chan?key=password` henceforth -leaking the channel key through the `/whois` IRC command (depending on IRC server -configuration). This is due to a long standing Irker bug. +1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty, + it defaults to `localhost`. +1. Optional. Under **Server port**, enter the server port of `irkerd`. If empty, it defaults to `6659`. +1. Optional. Under **Default IRC URI**, enter the default IRC URI, in the format `irc[s]://domain.name`. + It's prepended to every channel or user provided under **Recipients**, which is not a full URI. +1. Under **Recipients**, enter the users or channels to receive updates, separated by spaces + (for example, `#channel1 user1`). For more details, see [Enter irker recipients](#enter-irker-recipients). +1. Optional. Under **Colorize messages**, select the checkbox. irker will highlight your messages. +1. Select **Save changes** or optionally select **Test Settings**. + +## Enter irker recipients + +If you left the **Default IRC URI** field empty, enter recipients as a full URI: +`irc[s]://irc.network.net[:port]/#channel`. If you entered a default IRC URI there, you can use just +channel or user names. + +To send messages: + +- To a channel (for example, `#chan`), irker accepts channel names of the form `chan` and + `#chan`. +- To a password-protected channel, append `?key=thesecretpassword` to the channel name, + with the channel password instead of `thesecretpassword`. For example, `chan?key=hunter2`. + Do **not** put the `#` sign in front of the channel name. If you do, irker tries to join a + channel named `#chan?key=password` and so it can leak the channel password through the + `/whois` IRC command. This is due to a long-standing irker bug. +- In a user query, add `,isnick` after the user name. For example, `UserSmith,isnick`. -- cgit v1.2.3