On-Premises Tenant

For setting up syslog writer with an On-premises Tenant, you will need to carry out these additional steps before executing the docker run command.

Note: Below Linux commands are specific to Centos 6.9/10. You will need use an equivalent command for your specific Linux OS.

To set up an on-premises tenant:

  1. Ensure that the Tenant name is reachable.

    From the Linux machine, on which you are planning to setup the Syslog Writer, you need to make sure that the tenant name is reachable (Check with ping or curl command). 

    For example, if tenant URL is https://webportal.centsiem-1.com and the server IP address is 172.31.15.16 For this, you need to have this below entry in /etc/hosts file on the Linux machine.

    172.31.15.16 webportal.centsiem-1.com
  2. Install the Server Root CA certificate in CA Bundle.

    The Syslog Writer internally makes an HTTPS REST API call to the Tenant for OAuth access and fetching events. So, for successful SSL certificate verification, the CA authority needs to be a trusted one.  

    By design, for an On Premise tenant, the certificate is self-signed, so you must include its server Root CA certificate in CA store of Linux machine, on which the syslog writer will be setup.   

    Please note that in case you have provided your own certificate when installing the on-premise tenant (not self-signed), you will need to add that certificate to the CA store of Linux machine, instead of the server's Root CA certificate, as detailed in the steps mentioned below.

    And if your certificate issuer is a universally known authority, then you don't need to add it to the CA store of the Linux machine (Machine running syslog-writer).  

    For adding the Root CA certificate, first locate the certificate on Tenant Server machine, in path (similar to this), “C:\ProgramData\Centrify\Centrify Identity Platform\config\root_ca_public_certificate.cer” 

    Copy the above-mentioned Root CA certificate to a Centos 6.9/10 or RHEL 6.10 machine (the host, on which you will run syslog writer app). Also extract the syslog writer zip file cisp_syslog_writer.zip.

     Inside the extracted folder cisp_syslog_writer, there is scripts folder that contains a script which adds the Root CA certificate to CA bundle and verifies whether the update happened successfully. It also copies the updated CA bundle to the required folder (cisp_syslog_writer/data) later - where the syslog writer would expect it. 

    The script also takes a backup of the original CA bundle in ~/ca_backup_<datestamp> folder before updating it with Server Root CA certificate. You can restore the backed-up CA, in case of any unexpected problem. 

    If you are using a Centos 6.9/10 or RHEL 6.10 for syslog writer, you can run the provided script as shown below, to install the server Root CA certificate in CA bundle.

    sudo ./scripts/update_ca_on_centos_or_rhel.sh <path_of_Root_CA_certificate>

    On Ubuntu 16.04 or 18.04, you can use the script provided for ubuntu:

    sudo ./scripts/update_ca_on_ubuntu.sh <path_of_Root_CA_certificate>

    Note:   If you were able to use the provided scripts to update the CA bundle, you can skip the rest of this section, and directly jump to next step (Step #3) for running the syslog writer. 

    For other Linux versions, please refer to this URL to manually install the Root CA certificate:https://manuals.gfi.com/en/kerio/connect/content/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html 

    If you have manually updated the CA bundle - without using the provided update_ca scripts, carry out the below 2 steps to verify whether the CA bundle was updated successfully and to copy the updated CA bundle into the expected folder with the expected name.  

    1. Verify whether the above update to CA bundle happened successfully. Below is an example shown on Centos 6.9.
      1. Convert from DER encoded Root CA certificate copied from windows OPIE server into a PEM encoded certificate using below command.

        openssl x509 -in root_ca_public_certificate.cer -inform der -outform pem -out rootcacert.pem
      2. Use the newly created rootcacert.pem file to verify the updated CA bundle in below command. (For Ubuntu, replace the highlighted CAfile path in below command with /etc/ssl/certs/ca-certficates.crt)

        openssl verify -verbose -CAfile  /etc/pki/tls/certs/ca-bundle.crt rootcacert.pem

        If the Root CA certificate was added successfully to the CA bundle in step2, the output will be as below, otherwise it will show an error: In case of an error, you must not proceed to next step of starting syslog writer.

        rootcacert.pem: OK
    1. Copy the updated ca-bundle file to data folder, where the cisp_syslog_writer.zip was extracted.

      .. cisp_syslog_writer/data/ca-bundle.crt

       The CA certificates file copied into the data folder must have the same name, as used in the Docker run command that will be used to start syslog writer. (in our case, ca-bundle.crt).

      For Centos and RHEL the CA certificates file name is ca-bundle.crt. For Ubuntu, rename the CA certificates file copied in data folder to ca-bundle.crt or edit the docker run command mentioned ahead to use the name ca-certificates.crt.  

  3. Running the Syslog Writer

    Note:   Successful update of the CA bundle with Root CA certificate, as mentioned in previous steps, is a must, before proceeding further to start syslog writer. 

    Run the Syslog Writer after making sure that your present working directory is the cisp_syslog_writer folder, using an additional parameter as highlighted in the following Docker command:

    sudo docker run --name syslog-writer -it --log-driver json-file --log-opt max-size=10m --net=host -v `pwd`/data:/home/centrify-syslog-writer/data -e REQUESTS_CA_BUNDLE=/home/centrify-syslog-writer/data/ca-bundle.crt syslogwriter_image    

    Note that this path in above command: /home/centrify-syslog-writer/data is the path within the Docker container that is mapped from the `pwd`/data on your Linux machine via the -v option in the Docker run command.