xml2mysql - V 2.1 Matteo Risoldi 01/06/2004 README file See http://cern.ch/risoldi/filesdocs/186/instkit for updates and sources. --------------------- Installation --------------------- Unzip the class files archive in a directory. This will unpack the .class files that make the program and a .jar file containing the library needed to connect to MySQL. --------------------- Running --------------------- Given the prerequisite that you need to have a java interpreter in your path, run the program as follows: On windows: java -classpath ".\;.\mysql-connector-java-3.0.8-stable-bin.jar" xml2mysql On linux: java -classpath "./:./mysql-connector-java-3.0.8-stable-bin.jar" xml2mysql Please note: the MySQL server must be running for xml2mysql to operate. --------------------- What it does --------------------- This is a console program that can be used for configuration of the Run Control database. With xml2mysql it is possible to export a user configuration to XML files, and to reimport these files to configure another user. Configuring a new installation with settings from another machine is now a matter of simply distributing XML files, without having to manually go through all the configuration panels. Using xml2mysql it is possible to add configuration information to an already existing user, or to create new users. NOTE: The only manual thing needed after importing XML files will be to associate SubSystems with the ApplicationTypes (as detailed below). --------------------------- Using xml2mysql to EXPORT --------------------------- Say you have an installation of the Run Control where the user "paul" has all the settings you need. Say you want to export them to another machine, or another user. With xml2mysql you will create a bunch of XML files which you can then reuse for configuring another user. The steps to create the files are as follows: 1) You are asked for the existing root password. If the DB root access is not password protected, you can just press enter, otherwise provide the password. Note that this is the MySQL user root password, which is different from your system's root user's password. 2) The DB server is asked (default localhost). 3) The DB port is asked (default 3306). 4) The user you want to export data from is asked. You have to provide an existing username of the Run Control installation you are getting data from. 5) The output directory for the XML files is asked. You have to provide an existing directory. After this, xml2mysql connects to the database and dumps the user table contents into XML files. That's all, you can now distribute the files as you please. If you receive errors during the connection to the database, see the Troubleshooting section below. --------------------------- Using xml2mysql to IMPORT --------------------------- It is STRONGLY ADVISABLE to make a backup of your database before starting this procedure if you already have data in it. To do it, refer to the MySQL manual (search for "database backup"). *Please understand that backing up your data is your own responsibility.* Operation of xml2mysql is done through the command line in a series of steps. Note that it is possible that the root access to the DB is already protected with a password. Please, make sure you have this password before starting, or xml2mysql won't be able to modify the DB. If in doubt, try not providing the root password and see what happens. The steps are as follows: 1) You are asked for the existing root password. If the DB root access is not password protected, you can just press enter, otherwise provide the password. Note that this is the MySQL user root password, which is different from your system's root user's password. 2) The DB server is asked (default localhost). 3) The DB port is asked (default 3306). 4) The directory with configuration XML files is asked (default ./). From this directory, all .xml files will be uploaded into the database. 5) The name of the user to create/update is asked (default guest). 6) The password for the created user is asked (twice). Password is optional, and you can press enter if you don't want to define a password for the user. Note that if you are just updating a user, and not creating a new one, you don't need a password. 7) The host from which the user will access is asked (default localhost). This is it for the interactive part. Then the automated process begins: 1) xml2mysql verifies if the user already has an existing user table in the rs database. If yes, you are prompted if you want to reset it by deleting and recreating it. If you answer "y", the table will be deleted AND THERE IS NO TURNING BACK. A new table will be created, containing the XML information you are providing. If you answer "n" or just press enter, the XML files will just be added to the existing table (if possible). 2) If the user table did not already exist, it is created, and it will have the same name of the user. Also, user login/password information are added to the Run Control login system. 3) The user table is initialized with the default contents. 4) The XML files are inserted. Note that if a file conflicts with an entry already in the table (this could happen if you are adding info to an existing table), the file will be skipped and an error will be printed on screen. Please check the unicity of the information you are inserting. A final step needs to be taken: as the XML files don't contain information about what SubSystem contains what application types, you need to open the RC and go to ResourceService > System Definitions. Open the SubSystems tab, and associate your SubSystems with the correct ApplicationTypes. --------------------- Troubleshooting --------------------- Some common difficulties can be: Problem: Error messages saying that the access to the DB is denied. Solution 1: ...Are you sure the MySQL server is running? Solution 2: Check that you are providing the correct root password to the DB. Also, if the DB is configured not to use a root password, it will refuse access if you DO provide a password, so try also without giving an answer to the first question. Solution 3: If you are not accessing from the same host where the DB is, it might be impossible to access it unless you are given privileges. Either you can try to run xml2mysql directly on the DB host machine, or you can ask your DB administrator to give you access rights by running the MySQL client and giving the command GRANT ALL PRIVILEGES ON *.* TO 'root'@'yourmachinename'; (quotes must be included). Problem: When inserting a file, I get a message saying there is already a conflicting entry. Solution : You are trying to insert something which has a path and name identical to something else already in the DB. Edit the XML file, and change at least the name of the object you want to insert. Problem: After inserting an application (or something else) with a XML file, I can't remove or modify it with the GUI Solution : You forgot to edit the XML files to match the username you are providing. If your username is 'foo', open the XML files and look for a parameter similar to ID="guest:/SWPackages/RU" in the main tag of the file. The 'guest' part is the one you have to change to 'foo'. Actually, xml2mysql tries to fix this automatically, but in principle this problem could always happen. For entries that are already inside, you can't do much but delete them manually with the MySQL client, or re-run xml2mysql telling it to delete the user table (ONLY if you don't have other data there which has not been backed up!!!). For any other problem or malfunction, please write to matteo.risoldi@cern.ch providing a complete description. --------------------- F.A.Q. --------------------- Q: I have a user that I want to delete from the RC, because I want to recreate it completely from files. How do I do it? A: Be careful. This is a delicate operation. Open the MySQL client on the machine where you need to delete the user. Run the following commands: use rs drop table username; delete from system where name='username'; quit Substitute the name of the user for username. After this the user no more exists and you can recreate it from files. --------------------- Source code --------------------- The source code of xml2mysql can be found on http://cern.ch/risoldi/filesdocs/186/instkit --------------------- Thanks --------------------- L. Mirabito for providing the XML file templates. Michele Gulmini for the precious insight in the RC source code. R. Chierici and P. Bartalini for losing some of their time to show me how to play around with the GUI. A. Dierlamm and M. Weber for beta testing. --------------------- License --------------------- This software is made available through the GNU GPL License Version 2 or later, as defined in http://www.gnu.org/copyleft/gpl.html