====== Participation ======

===== Options =====

You can receive and send the data by using the following means:

  * Use the Warden client library (//warden_client//) by calling from your receiving or sending Python code.
  * Utilize //warden_filer// availeble in the //"contrib"// package. Filer runs as a daemon, communicates with the server and according to the selected direction it either receives events and saves them into chosen directory as individual files in the [[https://idea.cesnet.cz|IDEA]] format, or picks them from the directory and submits them to the server. You can then create or process the files in the framework or language of your choice.
  * Communicate directly with the server by using HTTP API (see README for //warden_client//). You can again utilize any suitable tools, including the command line (''curl'', ''wget'').

Client library and other supporting scripts are available at [[downloads]].

===== Registration =====

Choose the client name - it starts with the organisation domain name in reverse order. You can use the reversed DNS name of the machine, supplemented by the name of the application or the sensor. However, it is not wise to derive the name tail from the DNS for some detectors, namely honeypots, because it could spoil the honeypot location. For bigger organisations we recommend adding the name of the particular department (''cz.organisation.ict.probe1'') or other logical structure (''cz.organisation.detectors.probe1''). //The name can contain only letters, digits, underscores and dots and must not start by digit.//

Send following data to the [[contact|contact address]] by signed email (preferably by [[https://tcs.cesnet.cz/|TCS]] personal certificate):
  * chosen client name
  * machine DNS name
  * name and email address of the administrator (where Warden administrators and automated inspection scripts will be able to reach him)
  * type of the client (sender, receiver, testing), along with its brief description (method of detection, software, types of events produced, planned utilisation of the received events)
  * any additional information or questions

After successful registration (administrators may request additional information) the encrypted email with initial certificate generation token will be sent to you.

===== Configuration =====

Apply for the certificate by running:

<code sh>
./warden_apply.sh "https://warden-hub.cesnet.cz/warden-ra" the.client.name token
</code>

(Script is available at [[downloads#certificate_application_script|downloads]] page.)

The files //key.pem// and //cert.pem// will appear in the current directory (along with //csr.pem//, which is not necessary anymore, but you can save it for potential debugging).

Edit the configuration file - you can use following example:

<code json>
{
    "url": "https://warden-hub.cesnet.cz/warden3-sandbox",
    "certfile": "cert.pem",
    "keyfile": "key.pem",
    "filelog": {"level": "debug"},
    "name": "the.client.name"
}
</code>

"url" may contain ''https://warden-hub.cesnet.cz/warden3-sandbox'', or production server ''https://warden-hub.cesnet.cz/warden3'', it depends on agreement on the way of running-up and testing period with Warden server administrators .

In the case you use **warden_filer**, aforementioned configuration can be part of its configuration file.

===== Deployment =====

  * Try to receive or send the events. If not successful check the certificate and key paths, and search potential error description in the log messages (standard error or the.client.name.log file by default).
  * Sending client can test at //sandbox// server, which is completely separated by production traffic, see [[#configuration]].
  * Another option is to add //Test// to the //Category// field of the produced events.
  * Sending clients are registered for reception by default, so you can verify by using receiving client, that your events have the proper format. In particular, please check, that:
    * honeypot does not report its IP address (use anonymisation),
    * there are no IP addresses from the private address space - [[https://tools.ietf.org/html/rfc1918|RFC1918]], or any other network ranges which you would rather not publish.
  * If everything seems ok, ask at the [[contact|contact address]] for lifting the testing period and after approoval change the URL to the production server (see [[#configuration]]), and/or remove //Test// category if needed.
  * Check again, that everything gets sent properly. For repeated testing you can use //Test// category anytime even on the production Warden server - it gets ignored by both recipients and statistical modules.
  * Direct possible problem reports or further questions to the [[contact|contact address]].