This installation documentation is intended for workstations that include an installation of both Specify and MySQL, and wish to allow access to the Specify database by other workstations. This documentation is not intended for single instances of Specify that do not allow other workstations access, or MySQL server computers, which allow shared access across departments or campuses for multiple databases (not just Specify).
Specify 6 is a ‘thick-client’ application which is installed on (Windows, Linux or MacOS) desktop workstations. Specify uses Oracle Corp. database server software, MySQL, to manage collection data records. Before creating a Specify collections database, MySQL must be installed and running. It must then be configured to allow other workstations to access the Specify database created in MySQL. This document contains instructions for enabling access to your Specify database once MySQL has been installed. If MySQL has not been installed on your computer please refer to the document; Installing MySQL on a MacOS X for Specify, or Installing MySQL on Windows for Specify, depending on your operating system.
MySQL was created for networking, or allowing other computers to access its databases; however, the default installation of MySQL does not allow users on other machines to access the database. To enable this you must first configure your MySQL installation to use the network IP address of your workstation when listening for outside connections, and second, create and grant a Specify “Master User” (within MySQL, not Specify) the necessary permissions to access the MySQL database from other desktop computers. Both of these required steps are explained in the following sections.
Creating the Master Specify User and Granting Permissions in MySQL
Specify databases have user accounts and passwords, which can be created with several levels of permission and access. The highest level user account in Specify is a ‘manager’ account which has full access to all of Specify’s capabilities including the ability to create other Specify user accounts. A manager account is created by the Specify Wizard application, which is run after completing the configuration processes outlined in this document.
MySQL also has user accounts, login names and passwords; they are not the same as Specify user accounts. Configuring Specify requires the use of the ‘root’ account, which was setup during the MySQL installation, and also requires the creation of one other MySQL user account. The root account is referred to as the “Specify IT User” in the Specify documentation. The Specify IT User has powerful permissions to modify and update a Specify database in MySQL. It is used for the initial creation of a Specify database structure (schema) and for periodic software updates from the Specify Project, which update Specify’s database schema. When installing Specify updates always update the server workstation first. The Specify IT User name and password should be stored in a safe location where they can be easily retrieved. Loss of the IT User and Master User credentials will create significant, serious problems for updating Specify software and for database recovery from backups.
The second MySQL user account that a Specify installation requires is what we refer to as the “Master User” account. The Master User is the MySQL account used to actually create, edit and delete data records in a Specify database. The Master account is used ‘behind the scenes’ in Specify client software to provide database access to all of the Specify end-user (scientist) accounts created within the Specify client itself. A MySQL account is not needed for each Specify user as the Master account in MySQL handles all of the ‘backend’ database operations for every Specify user.
In a standalone workstation installation of Specify and MySQL on the same machine, the Master User accounts can be created by using the Specify Setup Wizard. For workstations that will be allowing access to their Specify database to other workstations the Master User account should be configured before running the Specify Setup Wizard. The key points for creating the Master User in MySQL are (1) to grant them privileges on a designated database name (2) to grant access to the database based on IP address range values.
Entering Commands
The commands shown in bold below are issued through a terminal. When entering the commands, replace the Courier font text below with the appropriate values for your setup. Note: You must be logged into your workstation as an administrator.
Note: MySQL Syntax is important! Extra spaces or typos will cause the commands to fail. You may wish to copy and paste the commands then edit the appropriate values.
[Italicized text in square brackets are comments.]
------------------- Start MySQL Session ------------------
[Open a terminal window on your workstation and log into MySQL, …/bin/mysql must be in the path or be the current directory:]
mysql -uroot–p
[After hitting Enter, type the MySQL installation root password]
[Next, create the Specify Master User and grant privileges. The user name for the account (MasterUsername) should not be an easily guessed word, avoid master’, ‘specify , ‘masteruser’, etc. You are designating a name for the database that will be built using the Specify Setup Wizard. This name will need to be entered in the appropriate window in the Setup Wizard. MySQL command syntax also allows IP ranges such as ‘ITUserName’@‘192.58.197.0/255.255.255.0’; where IP addresses rangefrom192.58.197.0to192.58.197.255. (MySQLdocumentationstatesthe’%'wildcardcharactercanbeusedin
specifying range addresses, but we have found them to cause errors and be interpreted incorrectly). Note: All Specify workstations which will access your Specify database in MySQL must be included in this IP range statement. The Master user is used by every Specify client workstation for database access. The MasterUserPassword should be strong, Oracle recommends using ASCII characters only.]
MYSQL> GRANT SELECT, INSERT, UPDATE, DELETE, LOCK TABLES ON DatabaseName.* TO 'MasterUsername'@'ClientIpAddressRange' IDENTIFIED BY "MasterUserPassword";
[Your ‘root’ user can only be accessed when mysql is running on localhost. To allow ‘root’ to be used locally while allowing other computers to access your workstation’s mysql databases, you will need to add this workstation’s IP address to the list of IP addresses that ‘root’ is allowed to log in from.]
MYSQL> GRANT ALL PRIVILEGES ON . TO 'root'@'YourWorkstationIPAddress' IDENTIFIED BY "RootPassword" WITH GRANT OPTION;
MYSQL> FLUSH PRIVILEGES;
MYSQL> EXIT;
------------------- End Terminal Session ------------------
Configuring the IP address of your workstation
For single workstations that do not wish to grant access to other workstations, the default installation of MySQL uses an IP address, (127.0.0.1), that is recognized as a ‘localhost’ or non-shared workstation. To allow other workstations to access your Specify database you must change the IP from this ‘localhost’ address to the actual IP address of the workstation. Configuring the IP address of the workstation is accomplished by editing the my.cnf (on Linux and MacOS X), or my.ini (on Windows) file in a text or source code editor or in the MySQL Workbench editor. When using a text editor you will need to run it as an administrator.
Also, if the IP address of your workstation changes, you will need to edit the my.cnf or my.ini file to reflect the change. For this reason it is recommended that you make your IP address static.
In the following procedure, replace the Courier font text below with the appropriate values for your workstation.
- Locate the my.cnf (Linux and macOS) or my.ini (Windows) file for your instance of MySQL.
If you are unsure of the location of the file a table documenting the location of the file based on the various versions of MySQL can be found here: http://dev.mysql.com/doc/refman/5.7/en/option-files.html.
- Open the file in a text, source code, or MySQL Workbench editor
- Locate this line: Bind-address = 127.0.0.1
- Replace 127.0.01 with the IP address of your workstation: Bind-
address = your IP address
If your my.cnf or my.ini file does not include a bind address locate the line [mysqld] and add the following line right under [mysqld]:
Bind-address = your IP address
- Save the file
- Restart MySQL
Once your workstation is configured to allow other workstations access, a name is designated for the Specify database, and a Master account is created, you may run the Specify Setup Wizard to build and populate the Specify database with data tables and add Specify user accounts. The Specify Setup Wizard (SpWizard.exe) – is an application distributed in the downloadable Specify installation package. When running the Specify Wizard application you will need to enter the designated database name, IP address of your workstation, the database port on the server (if changed from the MySQL default), and the Specify IT User (root) and Master User names and passwords.
The Specify Software Project periodically issues software updates; some of which update the Specify database schema and require collections scientist to use the MySQL root account credentials, referred to in Specify documentation as the “IT User” account, to authorize changes to the Specify schema in MySQL. The “Specify Master User” is used when creating new researcher user accounts and passwords within Specify.
Restoring data from backup files made through the Specify menu Backup function and which are usually stored on local disks requires the “Specify IT User” account credentials and should be completed on the workstation that hosts the database. Creating local Specify database backup files using the Specify Backup menu function does not require the IT credentials. Also in MySQL server configurations, in order for the Specify Backup and Restore menu commands to work, they require access to two MySQL programs in order to make local backup copies of a database and to restore them. The programs ‘mysqldump.exe’ and ‘mysql.exe’ are required on the workstation executing those commands for backup and restore operations, respectively. Their location on the workstation is indicated in a Specify preference window. They can be obtained from the appropriate installation package from Oracle or by contacting the Specify Software Project. We recommend daily backups of Specify databases. ‘Mysqldump.exe’ allows a Specify manager user to make a local backup in addition to, or instead of, a centrally organized backup process.
Using the Specify Setup Wizard to Populate and Customize the Specify Database
The Wizard has extensive embedded help and the help file for the Wizard is also available in its entirety on the Specify Project web site. It is useful to review the Specify Wizard documentation before running it as there are several configuration questions about your institution and collection that require choices during the process of completing the setup of your Specify database. Your answers to those questions change the way your Specify collection database behaves and handles your data.
When ready to run the Specify Wizard, find the file “SpWizard.exe” in the Specify installation /bin directory and run it.
In the first Wizard window enter the information for the new database: IT User name (root), IT User Password, Designated Database name, and Hostname (your workstation IP address), then click on “Create Specify Database”. This will initiate the process of creating Specify’s database tables and may take several minutes to complete.
Note: if you click on the “Test IT Login” button, and if the login is successful, the Setup Wizard will proceed to the next window. Before proceeding though, you must immediately use the “Back” button to return to the Database Information window, and click on the ‘Create Specify Database’ button, otherwise your Specify database tables will not be created and the Specify Wizard will eventually fail.
In the subsequent Wizard window, which asks you for the Master account information, enter the master username and password, and then click “Test Master Login”. This should return a message that your Master Login has worked and then you can proceed with the Wizard screens. If your Master account credentials do not allow you to login to the MySQL server, check your credentials for a misspelling.
Do NOT click on the “Create Master User” button on this window, as that will re-create your Specify master user account with MySQL access permissions restricted only to the workstation on which you are running the Specify Wizard. This will prevent other workstations from accessing your Specify database.
For help with the Setup Wizard, see the following documentation below: