SonarW Installation and Configuration

SonarW should only be installed on 64 bit Linux servers.

Prerequisites

Step 1. Checks

Check the following before you start:

Edit the following file:

/etc/security/limits.conf

Add the lines:

sonarw soft nofile 55536
sonarw hard nofile 55536

This can be done with the following command:

sudo sed -i '$ i\
sonarw           soft    nofile          55536\
sonarw           hard    nofile          55536
' /etc/security/limits.conf

Step 2. Raid setup

SonarW deployments should use disks RAID-0 or RAID-10 setup.

RAID-5 and RAID-6 do not typically provide sufficient performance.

It is recommended that you mount your raid and when prompted during the install select the mount point you created.

During the install a default data folder will be set to “/var/lib/sonarw” If you want to change it to another location (for example on your RAID) please refer to section “Changing the SonarW Data Folder” below.

Step 3. You must ensure an SSH server (such as OpenSSH) is running on the host.

Step 4. To access the SonarW Repository you will need your username and password, provided by jSonar. You’ll need to replace the instances of <your user name> and <your password> in the commands below with your specific credentials.

Installation on Ubuntu 14.04 LTS

Ensure you followed the instructions in the Prerequisites section

If you are running MongoDB on your local system and can not change your existing installs please contact jSonar for additional support prior to moving forward with this installation. MongoDB should be updated to version 3.4

If you are using MongoDB packages installed from the Ubuntu repository (as opposed to the MongoDB.org repository) and wish to continue using them, please contact jSonar for additional support prior to moving forward with this installation.

The following instructions will install/update MongoDB components on your server. If you are currently using MongoDB packages pulled from the Ubuntu repositories those will be removed and replaced by similar packages from repo.mongodb.org

Setting the MongoDB.org repository:

Open a terminal and enter the following commands:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 0C49F3730359A14518585931BC711F9BA15703C6
echo "deb [ arch=amd64 ] http://repo.mongodb.org/apt/ubuntu trusty/mongodb-org/3.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list

Update repository list:

sudo apt-get update

To remove existing Ubuntu-Mongo packages (as they conflict with the MongoDB.org packages):

sudo apt-get remove mongodb mongodb-server mongodb-clients mongodb-dev

Install MongoDB components from repo.mongodb.org:

sudo apt-get install mongodb-org-shell mongodb-org-tools

Enable automatic stack trace (and debugging):

Edit the file /etc/sysctl.d/10-ptrace.conf and change the last line to read “=0” and not “=1”:

sudo vi /etc/sysctl.d/10-ptrace.conf

The updated line should read:

kernel.yama.ptrace_scope=0

Save and exit.

Change your user to root, run this single command, then exit:

sudo su -
echo -n "0" > /proc/sys/kernel/yama/ptrace_scope
exit

Add Sonar repository GPG Keys:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv D2DC3407

Add Sonar Repository (Note: need to put your own user name & password in the command):

cat<<'EOF' | sudo tee /etc/apt/sources.list.d/jsonar.list
deb [arch=amd64] http://<your user name>:<your password>@repo.jsonar.com/ trusty main
EOF

Update:

sudo apt-get update

Install pip and pymongo:

sudo apt-get -y install build-essential python-dev
sudo apt-get -y install python3-pymongo
sudo apt-get install python-pip

Get Updates:

sudo apt-get update

Install SonarW:

sudo apt-get install sonarw

Install Sonar Oplog Tracker (SOT):

sudo apt-get install sonarot

Install SonarBackup:

sudo apt-get install sonarbackup

Install SonarSQL:

sudo apt-get install sonarsql

To setup SonarSQL run the next command and provide the required details (SonarW URI & root password):

sudo sonarsql-setup

Note: First you’ll be asked to specify the SonarW URI used by SonarSQL. Next you can specify the root password, either provide a password or leave empty (if you do not intend to use root).

Start the sonard service:

sudo start sonard

The installation is completed!

By default SonarW starts up with authentication enabled. There is a default user admin defined with a predefined password (admin). Upon completion of the installation you should login using this admin user and create a new user with either the userAdminAnyDatabase or the userAdmin role, with a secure password. This will disable the default admin user (that user exists only if there are no users defined in system.users).

If you choose to run without authentication you can stop SonarW, turn off authentication in /etc/sonar/sonard.conf and restart the sonard service.

Additional options and details:

If you want to keep SonarW at a specific version, you may want to do these steps in an LXC container (http://askubuntu.com/questions/293275/what-is-lxc-and-how-to-get-started)

In the future Sonar will be updated when you run:

sudo apt-get update

followed by:

sudo apt-get upgrade

or automatically by Ubuntu’s Software Updater.

Installation on Red Hat 7

Ensure you followed the instructions in the Prerequisites section

If you have already installed MongoDB on your local system and can not change your existing installation please contact jSonar for additional support prior to moving forward.

If you are running MongoDB on your local system you may have an incorrect version and should update to version 3.6

Setting mongo tools:

If updating from an older MongoDB refer to the instructions on the Mongo.org site (https://docs.mongodb.org/manual/tutorial/install-mongodb-on-red-hat/)

Please note that you need to install the 3.6 version of MongoDB.

Add the MongoDB 3.6 repo:

sudo cat <<'EOF' | sudo tee /etc/yum.repos.d/mongodb-org-3.6.repo
[mongodb-org-3.6]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/3.6/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-3.6.asc
EOF

Note: SonarW only requires the “mongodb-org-shell” & “mongodb-org-tools”

Therefore your install command should only include:

sudo yum install mongodb-org-shell && sudo yum install mongodb-org-tools

Add epel repository:

sudo rpm -U https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum-config-manager --enable epel
sudo yum-config-manager --enable rhui-REGION-rhel-server-optional

Add Sonar repository:

The following command will insert the following lines to /etc/yum.repos.d/jsonar.repo (Note: need to put your own user name & password in the “baseurl”):

cat <<'EOF' | sudo tee /etc/yum.repos.d/jsonar.repo
[Jsonar]
name=Jsonar Repository
baseurl=http://<your user name>:<your password>@rpm.jsonar.com/
enabled=1
priority=1
gpgcheck=0
EOF

Install pip:

sudo yum -y install python-pip

If you’re upgrading from an existing installation you need to get Updates:

sudo yum update

If installing HADR you must remove SELinux to allow your Main and Disaster Recovery machines to communicate:

sudo rpm -ev selinux-policy selinux-policy-targeted

Install SonarW:

sudo yum -y install sonarw

Install Sonar Oplog Tracker (SOT):

sudo yum -y install  sonarot

Install SonarBackup:

sudo yum -y install sonarbackup

Install SonarSQL:

sudo yum -y install sonarsql

To setup SonarSQL run the next command and provide the required details (SonarW URI & root password):

sudo sonarsql-setup setup

Note: First you’ll be asked to specify the SonarW URI used by SonarSQL. Next you can specify the root password, either provide a password or leave empty (if you do not intend to use root).

Start the sonard service:

sudo systemctl start sonard

Disable port blocking by RHEL firewall:

sudo iptables -F

The installation is completed!

By default SonarW starts up with authentication enabled. There is a default user admin defined with a predefined password (admin). Upon completion of the installation you should login using this admin user and create a new user with either the userAdminAnyDatabase or the userAdmin role, with a secure password. This will disable the default admin user (that user exists only if there are no users defined in system.users).

If you choose to run without authentication you can stop SonarW, turn off authentication in /etc/sonar/sonard.conf and restart the sonard service.

Connect to SonarW

Once everything is installed, SonarW’s sonard service will be running. You can connect to it using the standard MongoDB tools

mongo localhost:27117/admin -uadmin -padmin

To verify that you have connected to the correct server run:

> db.serverStatus()

from the Mongo shell. The “process” field should be set to “sonard”. Note that the pid will not be the same pid reported when you run status sonard, it is a child of that process.

Changing the SonarW Data Folder

When the SonarW package is installed the default data directory is /var/lib/sonarw. If you want to store data on a different directory (e.g. you setup a RAID array and want to store data on that RAID) you need to change the data directory for SonarW. This section describes how to manually change the data directory.

if you want to create a new data directory:

sudo mkdir -p /new/path/sonarw
sudo chown sonarw:sonar /new/path/sonarw

Stop the SonarW daemon (Ubuntu/upstart):

sudo stop sonard

or (if using RHEL/systemd):

sudo systemctl stop sonard

By default the data directory is located at /var/lib/sonarw/. If you want to keep your data, you should move this directory to the new path:

sudo mv /var/lib/sonarw/ /new/path/

You also need to change the “home” folder for sonarw:

sudo usermod --home /new/path/sonarw sonarw

If your system uses upstart (Ubuntu) as an init daemon change the file “/etc/default/sonard”, setting SONAR_HOME to the new path:

echo "SONAR_HOME=\"/new/path/sonarw\"" | sudo tee /etc/default/sonard

If you have a systemd system (Red Hat), change the file “/etc/sysconfig/sonard”, setting SONAR_HOME to the new path using:

echo "SONAR_HOME=\"/new/path/sonarw\"" | sudo tee /etc/sysconfig/sonard

Next time you start the SonarW daemon it will use the specified directory.

Ubuntu:

sudo start sonard

Red Hat:

sudo systemctl start sonard

File locations

  • sonard wrapper script: /usr/bin/sonard
  • sonard program files: /usr/lib/sonarw
  • sonard data (SONAR_HOME): /var/lib/sonarw
  • sonard default configuration: /etc/sonar/sonard.conf
  • sonard user-specific configuration: $HOME/.sonard.conf
  • sonard instance-specific configuration: $SONAR_HOME/sonard.conf

The data files in /var/lib/sonarw can only be accessed by the system user “sonarw”. To access these files, use:

`sudo -u sonarw`

followed by your command. For example, to list all the files in sonarw’s data directory:

sudo -u sonarw ls -lR /var/lib/sonarw/data

Command Line Parameters

SonarW almost always runs as a service and uses the sonard.conf file. In specific environments SonarW can be run from the command line and passed all it’s configuration parameters via the command line or in a config file, it is important to use the full path when running, e.g.:

/usr/lib/sonarw/sonard --max_part_size=100m --slavemode_on true

or:

/usr/lib/sonarw/sonard --config=/tmp/sonard.conf

Use -h to see all config command line options.

Instructions for Running SonarW with Kerberos Authentication

You must have a Kerberos KDC server running before setting up the client. In the example below assume that both KDC and administration server are running on “server”, the Kerberos realm is set at “JSONAR.KRB” and client has a hostname “client”.

To set up Kerberos on your system, make sure you have the latest version of SonarW installed, and the Kerberos user utilities:

sudo apt-get install sonarw krb5-user

You will be asked to enter a default realm name e.g. JSONAR.KRB. When you are prompted for the KDC and administration server, enter server. Specify a default domain which is provided as “jsonar.krb” in this example.

You can also update these parameters by updating the /etc/krb5.conf file. Verify that this file looks like this

[libdefaults]
        default_realm = JSONAR.KRB
...
...
[realms]
        JSONAR.KRB = {
            kdc = server
            admin_server = server
            default_domain = jsonar.krb
        }
...
...
[domain_realm]
...
...
        .jsonar.krb = JSONAR.KRB
        jsonar.krb = JSONAR.KRB
...
...

Ensure that /etc/hosts contains matching information about the server and client domains and you can ping the server from client and vice versa. Further, update the client name in the /etc/hostname file.

To confirm that this is working as expected, try the following commands, using the password “test” when prompted by kinit:

kinit sonarwuser
klist

If kinit returns without an error and klist outputs a principal name, Kerberos is working.

The next thing is to set up keytab files which contain pairs of kerberos principals and encrypted keys using the ktutils. Assuming sonarw is the name of the gssapi service and client is the hostname for the client

ktutil

add_entry -password -p  sonarw/client.jsonar.krb@JSONAR.KRB -k 1 -e rc4-hmac

add_entry -password -p  sonarw/client.jsonar.krb@JSONAR.KRB -k 1 -e aes256-cts

write_kt /etc/krb5.keytab

Ensure that the keytab file can be accessed by the sonarw service by changing the ownership

sudo chown sonarw:sonarw /etc/krb5.keytab

The next thing you need is the Mongo Enterprise shell. While all of the Mongo drivers support Kerberos, the standard Mongo shell does not support Kerberos authentication. You can download a copy of Mongo Enterprise at:

http://www.mongodb.com/customer-evaluation-downloads-development-versions

which does support Kerberos. The easiest thing to do is download the Mongo shell package for Ubuntu 14.04.

Install the appropriate SASL module to use Kerberos authentication with the Mongo shell:

sudo apt-get install libsasl2-modules-gssapi-mit

Configure SonarW so it will grant certain permissions to certain Kerberos users. With authorization off, connect to SonarW using the Mongo shell, then create some external database users. Note that you do not have to provide passwords for kerberos users.:

mongo localhost:27117
> use $external
> db.createUser( { user: 'sonarwuser@JSONAR.KRB', roles: [ { role: 'root', db: 'admin' } ] } )
> exit

Edit your sonard.conf by setting auth to true, and add GSSAPI to auth_mechanisms list and update the sasl_hostname which in this case is client:

# ...
auth=true
auth_mechanisms=MONGODB-CR, SCRAM-SHA-1, GSSAPI
sasl_hostname="client"
# ...

To authenticate, connect SonarW with its service principal on the Kerberos server. This requires that SonarW identifies itself with a particular hostname, and it has access to a keytab file with the corresponding service principal.

At this point you can restart SonarW and connect using the Mongo Enterprise shell. Enter the password “test” when prompted by kinit:

sudo restart sonard

mongo --host <server_ip> --authenticationMechanism=GSSAPI --gssapiHostName=localhost --authenticationDatabase='$external' --username sonarwuser@JSONAR.KRB'

What if I want to put the keytab file somewhere else?

Using /etc/krb5.keytab could be a bad idea in practice, because it allows any service on your system to access SonarW’s service principal. Instead, you may want to store it somewhere like /var/lib/sonard/sonard.keytab, and set permissions so only the sonardb user has access to the file:

sudo mv /etc/krb5.keytab /var/lib/sonard/sonard.keytab

Now we need to tell Sonar about its new keytab file. Edit /etc/default/sonard and add the following:

KRB5_KTNAME=/var/lib/sonard/sonard.keytab

Then, restart Sonar:

sudo restart sonard

If you are connecting to SonarW from JSON Studio when using Kerberos you need to supply a Kerveros service on the login screen. The default one is sonarw. Also note that the hostname you use should be known to the Kerberos service (using the fully qualified domain name).

Instructions for Running SonarW with LDAP Authentication

SonarW supports authentication of users using Lightweight Directory Access Protocol (LDAP) using SASL PLAIN mechanism. SonarW requires that sslauthd is already configured to use ldap mechanism and saslauthd daemon process is running before a client can authenticate against it.

Installation and setup of saslauthd

Install saslauthd

Ubuntu:

$ sudo apt-get install sasl2-bin

Redhat:

$ sudo yum install cyrus-sasl-2.1.26-20.el7_2.x86_64

Configuring

saslauthd

Ubuntu:

Edit /etc/default/saslauthd:

set START=yes
Find “MECHANISMS” and change the value to “ldap”
Save and exit

Update the upstart directory mode to 755:

$ sudo dpkg-statoverride --remove /var/run/saslauthd
$ sudo dpkg-statoverride --add root sasl 755 /var/run/saslauthd

RedHat:

Edit /etc/sysconfig/saslauthd:

Find “MECH” and change the value to “ldap”
Save and exit

saslauthd.conf

Edit /etc/saslauthd.conf ensure it has the following content:

ldap_servers: ldap://192.168.1.0 (change to the actual LDAP IP)
ldap_search_base: OU=jsonar-ou,DC=sonar1,DC=local (change OU, DC to match  your LDAP settings)
ldap_timeout: 10
ldap_filter: (|(userPrincipalName=%u)(sAMAccountName=%u)(CN=%u))
ldap_bind_dn: CN=Administrator,CN=Users,DC=sonar1,DC=local (change CN, DC to match your LDAP settings)
ldap_password: password (change to match your LDAP settings)
ldap_deref: never
ldap_restart: yes
ldap_scope: sub
ldap_use_sasl: no
ldap_start_tls: no
ldap_version: 3
ldap_auth_method: bind

Save & Exit.


Start saslauthd

Ubuntu:

$ sudo service saslauthd start
$ sudo update-rc.d saslauthd defaults

RedHat:

$ sudo systemctl start saslauthd
$ sudo systemctl enable saslauthd

Test LDAP authentication

In order to test the connection and authentication between your server and the LDAP server you need to run the next command from a terminal:

$ testsaslauthd -u <username> -p <password> -f <path of mux file>

username: User defined in the LDAP server

password: The password for the user on the LDAP server

path of mux file: Default is /var/run/saslauthd/mux

For example:

$ testsaslauthd -u 'John_Smith' -p 'abcd1234' -f /var/run/saslauthd/mux

The expected result (i.e. successfully authenticated):

0: OK "Success."

Configure SonarW

  • Edit /etc/sonar/sonard.conf

Enable authentication, ensure you have the “PLAIN” option set in the mechanism and enable ldap_socket:

# ...
auth=true
.
.
authenticationMechanisms = MONGODB-CR, SCRAM-SHA-1, PLAIN
.
.
ldap_socket = "/var/run/saslauthd/mux"
# ...

restart SonarW:

$ sudo restart sonard

Test login to SonarW using LDAP

First you need to create a User in SonarW

To create a user:

Login to SonarW using the Mongo shell with a user who has the privileges to add other users. Change DB to “$external”:

> use $external

Add user:

> db.createUser( {user : "John_Smith", roles: [ { role: "read", db: "myDB" } ]}

Notes:

  • You can use any of the User’s identity options: userPrincipalName, sAMAccountName or CN.
  • There is no password because the password is defined on the LDAP server

Test login using the LDAP user’s credentials

Replace the UN/PW with the credentials from your LDAP system:

> db.getSiblingDB("$external").auth(
    {
    mechanism: "PLAIN",
    user: "John_Smith",
    pwd:  "abcd1234",
    digestPassword: false
    }
)

expected result:

> 1

Return value 1 -> Means login successfully!