.. _regserverconfig: Registration Server Configuration ================================= .. _xmlimport: Importing XML With Initial Configuration Values to the Database --------------------------------------------------------------- The initial configuration of the Registration Server is performed based on values defined in the configuration file ``RegServerSetup.xml`` which must be placed in directory ``/usr/local/primebase/setup/``. The values included in this file are inserted into the Registration Server's MySQL database and in the PrimeBase configuration file ``pbvm.env``. Please refer to the *Registration Server Reference Guide* for more details on the individual options contained in this file. If you have any questions about this step, please contact your TeamDrive represenatative or TeamDrive support via e-mail at `support@teamdrive.net `_. Most of these values in ``RegServerSetup.xml`` can be left "as is" |---| you can modify and fine-tune most of these later via the Admin Console, if required. The most important sections that need to be filled out and updated are ```` (global Registration Server settings), ```` (provider-specific settings, including the provider user account required for logging into the Administration Console) and ```` (SMTP server configuration). Also, all occurences of ``regserver.yourdomain.com`` should be replaced with the domain name of your Registration Server throughout this file. To avoid "man-in-the-middle attacks", a cryptographic salt value is used to hash API requests. When you set up your own TeamDrive Host Server, this value needs to be provided during the installation and must match the one used on the Registration Server. You define this value in the tag ```` in the ``RegServerSetup.xml`` configuration file. One way to create this random hash salt value is running the following commands:: % dd if=/dev/urandom of=/tmp/random bs=1k count=1000 1000+0 records in 1000+0 records out 1024000 bytes (1,0 MB) copied, 0,0944645 s, 10,8 MB/s % sha1sum /tmp/random 4edd4f0a2e507b7c03b57cb414cbdeaf58f4a6ad /tmp/random After installation this checksum can also be obtained on the Registration Server Administration Console, from the ``APIChecksumSalt`` system setting (**Edit Settings -> RegServer**). .. Note:: Your Registration Server needs to be registered with the global TeamDrive Name Service (TDNS) before it can be installed. You need to submit the following configuration options from your ``RegServerSetup.xml`` file to the TeamDrive support team before you can proceed: * Your Provider Code (4 chars), as defined in ```` * The Registration Server's name, as defined in ```` * The Registration Server URL, as defined in ```` In return, you will receive your TDNS ID and a checksum, which you need to define in the settings ```` and ```` respectively. After you've updated the XML file to match your environment, change to ``/usr/local/primebase/setup``, start ``pbac`` and choose connection ``2 (TD2REG_WRITE)`` to execute the file ``RegServerSetup.pbt`` using the following commands:: [root@regserver ~]# cd $PRIMEBASEHOME/setup [root@regserver setup]# pbac PrimeBase Automation Client. Copyright 2007-2014, PrimeBase Systems GmbH. Web: http://www.primebase.net E-mail: support@primebase.net Select a connection by number, and Login: Or enter 'A' to add, 'D' to delete, or 'E' to edit an entry. Or enter 'T' to move an entry to the top of the list. File: ./connect.def Alias Protocol Server -------------------- -------------------- -------------------- 0 (exit without connecting) 1 td2as Internal/Runtime 2 TD2REG_WRITE Internal/Runtime OpenServer 3 TD2REG_SLAVE Internal/Runtime OpenServer ----------------------------------------------------------------- Connection..: 2 User........: teamdrive Password....: ********* 1: Connected to "TD2REG_WRITE" as "teamdrive". For a list of commands enter "#help" 1: 1> execute file "RegServerSetup.pbt"; 1: 2> go 1: Execution begins... Registration Server Configuration --------------------------------- Enter one of the following commands, followed by 'go': Initial server setup: setup:init(); Updating server settings: setup:modify(); Compare XML configuration file with server data: setup:compare(); Adding a new provider: setup:newProvider(''); Update an existing provider: setup:updateProvider(''); Delete a provider: setup:deleteProvider(''); 1: Execution completed successfully. 1: 1> setup:init(); 1: 2> go 1: Execution begins... Connecting to MySQL Server using Plugin: "mysqlplugin.so" ... Connected. Setting PBVM Decimal Format to "9999.9" [...] Waiting for initial Public / Private Key creation for your registration server... Done. Your registration server needs to be added to the list of available servers in the TeamDrive Name Service Network. Please send the following output to TeamDrive Systems: [RegServerName] reg-server-url=http://regserver.yourdomain.com/pbas/td2as/reg/ notification-url=http://regserver.yourdomain.com/pbas/td2as/reg/ media-server-url=http://regserver.yourdomain/pbas/td2as/reg/ update-program-url=http://regserver.yourdomain.com/pbas/td2as/upd/update.xml balance-url=http://regserver.yourdomain.com/pbas/td2as/reg/ log-upload-url=http://regserver.yourdomain.com/logupload/upload.php redirector-url=http://regserver.yourdomain.com/pbas/td2as/bal/redirector.htm ping-url=http://regserver.yourdomain.com/pbas/td2as/reg/ping.xml Authorization sequence: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Initial setup sucessfully completed! You can now start the TeamDrive Registration Server. 1: Execution completed successfully. 1: 1> quit 1: Closed. The Registration Server has now been configured and is ready for operation. Submitting your Server's Authorization Sequence ----------------------------------------------- Each Registration Server has a unique "Authorization Sequence" that is required to securely communicate with the Master Registration Server (usually "TeamDriveMaster"), e.g. to send invitations to users which are registered on other TeamDrive Registration Servers in the TDNS-Network. After you have set up your own Registration Server, you need to submit this information to TeamDrive Systems, so your Server is allowed to contact the Master Registration Server. The authorization sequence is printed out by ``RegServerSetup.pbt`` during the initial installation:: [RegServerName] reg-server-url=http://regserver.yourdomain.com/pbas/td2as/reg/ notification-url=http://regserver.yourdomain.com/pbas/td2as/reg/ media-server-url=http://regserver.yourdomain/pbas/td2as/reg/ update-program-url=http://regserver.yourdomain.com/pbas/td2as/upd/update.xml balance-url=http://regserver.yourdomain.com/pbas/td2as/reg/ log-upload-url=http://regserver.yourdomain.com/logupload/upload.php redirector-url=http://regserver.yourdomain.com/pbas/td2as/bal/redirector.htm ping-url=http://regserver.yourdomain.com/pbas/td2as/reg/ping.xml Authorization sequence: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Take note of these values and submit them along with your provider code and ``RegServerName`` to `support@teamdrive.net `_. If required, the authorization sequence can also be obtained later on from the Registration Server's Administration Console (**Edit Settings -> RegServer -> AuthorizationSequence**). .. _apichecksumsalt: Post-install Checks ------------------- After the initial installation and configuration, you should perform some checks if the registration server works properly. .. _sendingmail: Sending Email via PBAC ~~~~~~~~~~~~~~~~~~~~~~ One of the most important tasks for the registration server is sending registration and notification emails to the TeamDrive client users |---| it's essential that this works. The Registration Server assumes a functional mail configuration that allows sending messages to arbitrary email addresses. It's possible to use a local or remote MTA, the mail configuration is defined in the ```` section of the ``RegServerSetup.xml`` setup file. The details of configuring a local MTA are out of the scope of this document, this heavily depends on your local environment. You need to be aware of topics like "Sender Policy Framework" (SPF), to avoid that emails sent by your Registration Server are considered to be Spam by other mail servers. .. Note:: The PrimeBase Framework is only capable of sending out email using plain SMTP via TCP port 25 to a local or remote MTA. If your mail server requires some form of authentication or transport layer encryption like SSL/TLS, you need to set up a local mail server that relays all outgoing email from the TeamDrive Registration Server to your MTA using the appropriate protocol and credentials. We recommend configuring a local Postfix instance for this. See the Postfix SMTP client documentation at http://www.postfix.org/smtp.8.html for details. You can perform the following steps to perform a mail sending test from within the PrimeBase Application Environment. Start the ``pbac`` tool using connection ``1 td2as`` and enter the following command line on the prompt. Please change the email addresses to suit your environment:: [root@regserver setup]# pbac PrimeBase Automation Client. Copyright 2007-2014, PrimeBase Systems GmbH. Web: http://www.primebase.net E-mail: support@primebase.net Select a connection by number, and Login: Or enter 'A' to add, 'D' to delete, or 'E' to edit an entry. Or enter 'T' to move an entry to the top of the list. File: ./connect.def Alias Protocol Server -------------------- -------------------- -------------------- 0 (exit without connecting) 1 td2as Internal/Runtime OpenServer 2 TD2REG_WRITE Internal/Runtime OpenServer 3 TD2REG_SLAVE Internal/Runtime OpenServer ----------------------------------------------------------------- Connection..: 1 User........: 1: Connected to "td2as" as "". For a list of commands enter "#help" 1: 1> $sendmail ("from_address@example.com", "to_address@example.com", "Subject", "Mailtext"); 1: 2> go 1: Execution begins... 1: Execution completed successfully. If you did not get any error message and the email arrives at the account identified by the second parameter, the mail service is configured correctly. In case of errors, check your mail server's log files and see chapter :ref:`troubleshooting` for hints about resolving common issues.