The Fedora server distribution comes with several command-line utilities that can be used to start and stop the Fedora server and to control the operation of that server. Some of these will be used by a site's repository administrator fairly regularly, while others may only rarely or never be needed. A description and usage instructions for each follows.
This guide assumes you have correctly installed the Fedora server distribution as per the install guide, including having set up your PATH and FEDORA_HOME appropriately. Additionally there are many other issues involved in initially setting up a Fedora repository these are explained in the command-line scripts are located in FEDORA_HOME/server/bin/. In Windows, these commands resolve to batch files (.bat); in Unix, they resolve to shell scripts (.sh).
Before the Fedora server is started you must run the Fedora setup utility to put a security configuration in place. See the guide for Securing Your Fedora Repository for a full discussion of the four configuration options. To select your base security configuration, run the "fedora-setup" command-line utility. This utility requires a single argument which is the name of the base security configuration you wish to use.
Under Windows:
Under Unix:
The valid values for configuration-name include:
- ssl-authenticate-apim
- ssl-authenticate-all
- no-ssl-authenticate-apim
- no-ssl-authenticate-all
The fedora-setup utility initializes one of the four base security configurations by copying a set of configuration files into the distribution tree. The contents of these configuration files will vary depending on the base security configuration selected. The resultant functionalities of the four possible base security configurations are described in more detail below. You can rerun the Fedora setup utility at any time to change your repository configuration. Just stop the server, run fedora-setup, and restart the server. The setup utility automatically puts an appropriate version of the three necessary Fedora configuration files into play:
fedora.fcfg - Fedora server configuration file
web.xml - Fedora Tomcat web application configuration file; controls whether basic authentication and SSL are enabled for API-M and API-A
beSecurity.xml - Fedora backend services configuration file; controls security for services calling back to Fedora (see beSecurity Configuration document for details)
fedora-start
or
fedora-start mckoi
Where:
fedora-start
Note: Before starting the Fedora server, a decision about what security configuration to use needs to be made (see fedora-config) and several decisions need to be made pertaining to the overall setup of the fedora-server need to be made, (see the Fedora Installation and Configuration Guide) and the database that is to be used in conjunction with the Fedora server (either MySql or McKoi or some other custom solution) needs to be started and initialized.
fedora-stop
This command is used to cleanly stop the Fedora server. This might need to be done when the configuration of the server is changed or to prevent all access to the repository while certain systems administration tasks are performed, or to run the program fedora-rebuild listed below.
fedora-rebuild
fedora-rebuild is an interactive utility that can be used when the Fedora repository is somehow corrupted. When this occurs either the SQL database of the Resource-Index become unusable, and usually the Fedora server will refuse to start. The SQL database (either MySQL or McKoi) caches some of the data stored in the repository to enable simple searching and to speed access to the repository.
In the past, under some circumstances the SQL database could become corrupt, which would then require the entire repository to be deleted and all of the digital objects in the repository to be manually re-ingested. The fedora-rebuild utility allows the Fedora administrator to merely purge the database used by the Fedora server, and re-configure the database (using either mysql-config or mckoi-init) and then run this utility to restore the repository to a rational, usable state. Additionally, if the Fedora administrator want to change from using the McKoi database to using the MySQL database, (or from MySQL to McKoi) the existing database can be purged, the fedora configuration file (fedora.fcfg) can be edited, and the fedora-rebuild utility can then be run to correctly populate the tables in the new database system.
Similarly, the Resource-Index files that are used for more advanced searching could occasionally become corrupted, which would prevent the Fedora server from starting. The fedora-rebuild utility can also be used to rebuild the Resource-Index files if this problem occurs.
When you run the utility, a text menu appears, allowing you to specify whether you need to rebuild the SQL database or rebuild the Resource-Index files. See below for a step-by-step description of how to recover from a corrupted MySQL database.
fedora-reload-policies
One of the main features added to version 2.1 of Fedora is improvements in access security (as described in the document [link to Bill's doc]) This access security is specified using XACML files which detail what persons or groups are allowed to perform various actions to the repository. Many of these XACML policies are applied for all actions and access attempts peformed on the repository as a whole. These "repository-wide" XACML policies are only loaded at the time the Fedora server is started. If the Fedora server administrator needs to change one or more of these repository-wide policies, this command can be used to tell the running Fedora server to reload all of the repository-wide policies. The alternative to using this command is to stop the Fedora server, and restart it.
validate-policy [policyFilename]
Where:
One of the main features added to version 2.1 of Fedora is improvements in access security (as described in the document [link to Bill's doc]) This access security is specified using XACML files which detail what persons or groups are allowed to perform various given actions to the repository. If the Fedora server administrator creates a new XACML policy to broaden the existing access policies or to more tightly restrict access, the newly created policy should be run through this program to ensure that the XACML policy is well-formed before attempting to install it in the Fedora server.
mckoi-init [fedoraDBUser] [fedoraDBPass]
Where:
Example:
mckoi-init fedoraAdmin fedoraAdmin
Initializes the McKoi database so that it can be used by the Fedora server. After it is initialized (which generally only needs to be done once) you will need to start the McKoi database with the mckoi-start command listed below.
mckoi-start
The mckoi-start command is used to start the McKoi database, after it has been initialized via the mckoi-init command. Note that if you are using the McKoi database this command must be performed before the Fedora server is started. Also note that if you choose to use the MySQL database, or any other database system, this command is not needed.
mckoi-stop [fedoraDBUser] [fedoraDBPass]
Where:
The mckoi-stop command is used to stop the McKoi database, after it has been started via the mckoi-start command. Note that if you are using the McKoi database this command must be performed after the Fedora server is stopped. Also note that if you choose to use the MySQL database, or any other database system, this command is not needed.
mysql-config [installDir] [dbaUser] [dbaPass] [fedoraDBUser] [fedoraDBPass] [dbName] [mysql41_flag]
Where:
The mysql-config command line builds all of the necessary tables within the MySQL database so that the Fedora server can be run using MySQL as its backing store. If you plan to use the McKoi database, this command is not necessary.
mysql-drop-db [installDir] [dbaUser] [dbaPass] [dbName]
Where:
This command can be used to delete all of the database tables used by the Fedora server. It might be needed if the database gets corrupted, as described above for the command fedora-rebuild.