==== ParkNPark ==== High-Performance Real-Time Fault Tolerant Baseline Demonstration ParkNPark is a three-tier, multi-client application that simulates a parking lot. The client represents a single car. The middle tier and database servers manage the parking lot and level states as well as which parking lot and level each car is on. A car can either be in one lot or not in any lot. This application is split into six folders: buildJar Build system client Client database Database state scripts sacredServer CORBA naming service server Middle tier server tests Testing manager How to run ParkNPark: 0. Prerequisites 1. Setting up the database server 2. Restoring the database 3. Running the CORBA naming service 4. Running the replication manager 5. Running the middle tier server 6. Running the client How to stop ParkNPark: 7. Stopping the client 8. Stopping the middle tier server 9. Stopping the replication manager 10. Stopping the CORBA naming service 11. Stopping the database server Additional sections: 12. Building the project 13. Running one measurement 14. Running all measurements Note that you can get more detailed command line parameters and documentation from each command by running it with the --help command line parameter. As an example, running the following command in the client folder will get all the possible command line options for the client: ./client --help Any missing parameters will also display the help page along with an error message describing what was missing. If you want to do remote debugging, run the -debug variant of the program that you want to run and then, in Eclipse, connect to port 7790 of the host that you ran that -debug command on. As an example, the following command will run the client in debug mode: ./client-debug --num-clients 1 --num-servers 2 --detection-timeout 1500 The -debug variants will wait for Eclipse to connect before starting. === 0. Prerequisites === This application requires the Sun Java 5 platform JDK and a recent Linux distribution. Sun JDK 1.5.0_06, which implements the Sun Java 5 platform, exists in /afs/ece.cmu.edu/class/ece749/public_html/teams-06/team6/jdk1.5.0_06 This can also be downloaded from Sun Microsystems's web site at http://java.sun.com/j2se/1.5.0/download.jsp If you are not using the /afs/ece.cmu.edu/class/ece749/public_html/teams-06/team6/jdk1.5.0_06 location to run Sun Java 5, then you will need to edit the client/client, server/server, and sacredServer/nameservice script files with a text editor. In each of those files, replace /afs/ece.cmu.edu/class/ece749/public_html/teams-06/team6/jdk1.5.0_06 with the root installation path of your Sun Java 5 JDK installation. Ensure that your Java path is Sun Java 5. To do this, replace ${JDK} with your Sun Java 5 JDK root installation path in the following line and run it on the command line: ${JDK}/bin/java -version As an example, if your Sun Java 5 JDK installation path is /usr/lib/java/versions/1.5.0_06, then you will replace ${JDK} in the above line with this path so that the command to run is the following: /usr/lib/java/versions/1.5.0_06/bin/java -version If the first line begins with the following, then you have the correct path. Otherwise, verify your Sun Java 5 JDK installation path and try again. java version "1.5 If your computer's external network interface is not eth0, then you will need to replace eth0 with your network interface's name in the server/server and sacredServer/nameservice script files. A text editor that supports find-and-replace can accomplish this task. As an example, if your external network interface is wlan0, then replace all occurrences of eth0 with wlan0 in those three script files. The scripts use this to get the IP address that CORBA will use to create objects on. With the prerequisites complete, you can now get the database server up and running. === 1. Setting up the database server === MySQL comes packaged in a ready-to-run tar.gz file. This file has been successfully installed and run on girltalk and clue, though it should also work on other servers. Follow these steps to set up the MySQL database on a server: 1. Change the current working folder to /tmp with the following command: cd /tmp 2. Decompress the ParkNPark MySQL package with the following command as one line with no space between team6/ and final_demo: tar xfz /afs/ece.cmu.edu/class/ece749/public_html/teams-06/team6/ final_demo/database/ParkNParkMySQL.tar.gz 3. Change the current working folder to /tmp/ParkNParkMySQL with the following command: cd /tmp/ParkNParkMySQL 4. Start up the MySQL server in the background with the following command: ./mysqld 5. You should see the following output. If you do not, please try using another server such as girltalk: 060505 20:57:10 InnoDB: Database was not shut down normally! InnoDB: Starting crash recovery. InnoDB: Reading tablespace information from the .ibd files... InnoDB: Restoring possible half-written data pages from the doublewrite InnoDB: buffer... 060505 20:57:10 InnoDB: Starting log scan based on checkpoint at InnoDB: log sequence number 0 60969640. InnoDB: Doing recovery: scanned up to log sequence number 0 60969640 060505 20:57:10 InnoDB: Started; log sequence number 0 60969640 060505 20:57:10 [Note] ./bin/mysqld: ready for connections. Version: '5.0.20-standard' socket: '/tmp/ParkNParkMySQL/mysql-team6-slackers.sock' port: 13306 MySQL Community Edition - Standard (GPL) 6. Because MySQL is running in the background, press Enter to see the shell prompt again MySQL is now running. Please make a note of the server that you started MySQL on so that you can tell the other system parts where it is. === 2. Restoring the database === The database will already be in its initial state when the database is started, but in case if any database problems are encountered due to database sabotage or other nefarious activities, this section explains how to restore the database's initial state. To restore the state of the production database, run the following commands while on the the server that you started MySQL on: 1. Change the current working folder to the database folder. If the current working folder is final_demo, then run the following command: cd database 2. Run the restore-database-girltalk script by running the following command (it will run even if your database server is not girltalk): ./restore-database-girltalk 3. When prompted for the password, type in the following password and press the return key: procrastinators 4. The production database should now restore to its initial state The database is now in its initial state. === 3. Running the CORBA naming service === To start the CORBA naming service, which is required to successfully run the server and the client, follow these steps: 1. Change the current working folder to the sacredServer folder. If the current working folder is final_demo, then run the following command: cd sacredServer 2. Start the CORBA naming service by running the following command: ./nameservice 3. Return to the final_demo folder cd .. 4. The CORBA naming service is now started. No messages are displayed by the CORBA naming service unless if problems exist During the startup process, the nameservice script will write out its IP address to the nameserver-host file. The server and client scripts will reference this file to know which host to use as the CORBA naming service's IP address. After the CORBA naming service is up and running, you may now start the middle tier server. === 4. Running the replication manager === To start the replication manager, you should first start the CORBA naming service. Failure to start the CORBA naming service first will cause the middle tier server to display an error message indicating that condition. If the replication manager does not have access to the sacredServer/nameserver-host file that the nameservice script created, then follow these steps (ignore these steps otherwise; if the servers share the same AFS space, then these steps can be ignored because the sacredServer/nameserver-host file is shared): 1. Open the sacredServer/replicationmanager script in a text editor 2. Comment out the line that starts with NSHOST=$(cat ../sacredServer/ by inserting a # character at the beginning of that line 3. Remove the # character from the beginning of the next line 4. Replace the IPv4 address on the line from the previous step with the IPv4 address of the CORBA naming service 5. As an example, if your CORBA naming service is running on 1.2.3.4, then the NSHOST lines of your file must look like the following: #NSHOST=$(cat ../sacredServer/nameserver-host) NSHOST=1.2.3.4 To start the replication manager, follow these steps: 1. Change the current working folder to the sacredServer folder. If the current working folder is final_demo, then run the following command: cd sacredServer 2. Start the replication manager by running the following command as one line, replacing girltalk with the database server that you ran MySQL on and adjusting the num-clients and num-servers parameters to any values that you want (these numbers are used for logging file names): ./replicationmanager --num-clients 1 --num-servers 2 --jdbc-url jdbc:mysql://girltalk:13306/ece749_team6 --detection-timeout 1500 3. The above command starts the replication manager. The following lines should appear or something similar to it. If an error appears instead, then fix the runtime condition that caused that problem and try again. Starting the CORBA ORB Activating the CORBA root POA Fetching the ParkNPark name service context ParkNPark name service context not found; creating Registering the replication manager name with the CORBA naming service Fetching the server list from the naming service Looking up the primary server from the name service No servers are active at this time Activating the last registered server No servers are active; notifying name service that no server is primary No primary server was registered Server running. 4. Return to the final_demo folder cd .. 5. The replication manager is now started Now that the replication manager is up and running, you can now run the middle tier servers. It's also possible to start the servers before starting the replication manager, though it's best to start the replication manager first so that it can keep track of all servers as soon as each one comes up. Note that the replication manager retrieves a list of existing servers from the name service when it starts up and uses that as its active server list, testing those servers and removing the servers that cannot be reached in the process. As a result, you can kill the replication manager and start it back up again without having to restart the middle tier servers. When faulty middle tier servers are restarted, they are restarted in the background on their respective servers. As a result, these restarted instances are hidden from view, but they can be killed with the ./killserver script in the final_demo/server folder. The replication manager will continue to restart servers that are killed until the replication manager is killed before the servers are killed. If you get an error from the replication manager regarding its inability to successfully restart a server, then please ensure that the JDBC URL that you gave to the replication manager on the command line is exactly correct. The replication manager does not verify the passed-in JDBC URL, so if it is incorrect, then you won't know except for the inability of a restarted server to properly start up. A possible future enhancement can make this condition clearer to the user. If all the servers are killed quickly before the replication manager has a chance to restart them, then the replication manager might unregister the primary name from the name service and thus cause any waiting clients to give up, thinking the system is down. A possible future enhancement can avoid this by not unregistering the primary name from the naming service until several seconds have elapsed and no server has become registered. To work around this, hold off on killing the last server when killing all servers until the replication manager has restarted at least one killed server. === 5. Running the middle tier server === To start the middle tier server, you should first start the CORBA naming service. Failure to start the CORBA naming service first will cause the middle tier server to display an error message indicating that condition. The replication manager does not need to be up when you start the middle tier server, but it is preferred. If the replication manager was not running when the middle tier server was started, the replication manager will discover the server via the naming service when it starts up. If the server does not have access to the sacredServer/nameserver-host file that the nameservice script created, then follow these steps (ignore these steps otherwise; if the servers share the same AFS space, then these steps can be ignored because the sacredServer/nameserver-host file is shared): 1. Open the server/server script in a text editor 2. Comment out the line that starts with NSHOST=$(cat ../sacredServer/ by inserting a # character at the beginning of that line 3. Remove the # character from the beginning of the next line 4. Replace the IPv4 address on the line from the previous step with the IPv4 address of the CORBA naming service 5. As an example, if your CORBA naming service is running on 1.2.3.4, then the NSHOST lines of your file must look like the following: #NSHOST=$(cat ../sacredServer/nameserver-host) NSHOST=1.2.3.4 To start the middle tier server, follow these steps: 1. Change the current working folder to the server folder. If the current working folder is final_demo, then run the following command: cd server 2. Start the middle tier server by running the following command as one line, replacing girltalk with the database server that you ran MySQL on and adjusting the num-clients and num-servers parameters to any values that you want (these numbers are used for logging file names): ./server --num-clients 1 --num-servers 2 --jdbc-url jdbc:mysql://girltalk:13306/ece749_team6 3. The above command starts the server. The following lines or something similar should appear. If an error appears instead, then correct the runtime condition that caused that error and try again. Starting the CORBA ORB Activating the CORBA root POA Fetching the name service reference Creating the client manager factory Fetching the ParkNPark name service context Registering server as boggle-172.19.132.112 with the CORBA naming service Notifying the replication manager that we are now active Server running. Server console: f Flush the logs to disk h Hose the database server connection k Kill server (but flush the logs first) x Exit 4. Return to the final_demo folder cd .. 5. The middle tier server is now started If you run the server and the client on the same computer and in the same UNIX login session, the server messages will appear on the display along with the client's messages. To avoid this, run the clients and servers on separate UNIX login sessions. Now that the server is up and running, you can now run the clients successfully. === 6. Running the client === To start the client, you should first start the CORBA naming service. Failure to start the CORBA naming service first will cause the client to display an error message indicating that condition. In addition to starting the CORBA naming service, at least one middle tier server should be started and registered with the same CORBA naming service that the client is configured to use. Failure to meet these conditions will cause the client to display an error message indicating that condition. The client will connect to a randomly-chosen registered middle tier server. If no registered middle tier servers are working or if no middle tier servers are registered, then the client will display an error message indicating that condition and exit. If the client does not have access to the sacredServer/nameserver-host file that the nameservice script created, then follow these steps (ignore these steps otherwise; if the servers share the same AFS space, then these steps can be ignored because the sacredServer/nameserver-host file is shared): 1. Open the client/client script in a text editor 2. Comment out the line that starts with NSHOST=$(cat ../sacredServer/ by inserting a # character at the beginning of that line 3. Remove the # character from the beginning of the next line 4. Replace the IPv4 address on the line from the previous step with the IPv4 address of the CORBA naming service 5. As an example, if your CORBA naming service is running on 1.2.3.4, then the NSHOST lines of your file must look like the following: #NSHOST=$(cat ../sacredServer/nameserver-host) NSHOST=1.2.3.4 To start the client on a Linux machine, follow these steps: 1. Change the current working folder to the client folder. If the current working folder is final_demo, then run the following command: cd client 2. Start the client by running the following command, adjusting the num-clients and num-servers parameters to any values that you want (these numbers are used for logging file names): ./client --num-clients 1 --num-servers 2 --detection-timeout 1500 3. The above command starts the client as a foreground process. The following lines should appear. If an error appears instead, then please correct the runtime condition that caused that error and try again. Server successfully obtained ParkNPark Following is the List of Lots. 1. Lot 1 2. Lot 2 3. Lot 3 4. Lot 4 Enter your choice and press return (press 0 to exit): 4. The client is now started To start the client on a Windows or OS X machine, follow these steps: 1. Ensure that the java or java.exe command in your PATH runs Sun Java 5 and not any earlier version 2. Run the following command in the client folder, replacing ${NSHOST} with the IPv4 address of your CORBA naming service and adjusting the num-clients and num-servers parameters to any values that you want (these numbers are used for logging file names): java -jar Client.jar -ORBInitialHost ${NSHOST} -ORBInitialPort 7777 --num-clients 1 --num-servers 2 --detection-timeout 1500 3. The above command starts the client as a foreground process. The following lines should appear. If an error appears instead, then please correct the runtime condition that caused that error and try again. Server successfully obtained ParkNPark Following is the List of Lots. 1. Lot 1 2. Lot 2 3. Lot 3 4. Lot 4 Enter your choice and press return (press 0 to exit): 4. The client is now started The client has two main states: Car In Lot and Car Not In Lot. When the car is not in a lot, you will be prompted to enter a lot choice or, if you want to exit, 0. Pressing 0 and the return key will exit the client. A valid parking lot number will attempt to enter that parking lot. An invalid parking lot number will inform the user of the invalid entry and ask again. After entering a parking lot, you can exit the lot or, if the lot has multiple levels, move up or down levels. The system will inform the user of the available levels upon entry into the parking lot: Available level(s) for lot 1 are: Level 1 Level 2 Level 4 Current level: 1 U. Move Up X. Exit Lot Enter your choice: If the lot that you tried to enter is full, then the client will display a list of parking lots that have availability, sorted by closest distance first: This Lot is full! Other Available Lots are: 1.Lot1 2.Lot2 3.Lot3 Enter your choice and press return (press 0 to exit): The following commands apply to the Car In Lot mode: U. Move up one level D. Move down one level X. Exit the parking lot A car can only exit the parking lot on an exit level, which is presently the bottom level in all cases. A car can not move below the lowest level, nor can a car move above the top level. === 7. Stopping the client === To exit the client, exit the lot that you are in if you are in a lot and then type zero and press the Enter key. If you were not in a lot, simply typing zero and pressing the Enter key will work. When you exit the client, the following message will appear before the client exits: Closing the client manager at the server CORBA communication problems will cause the client to exit. The next version will introduce fault tolerance through server failover. === 8. Stopping the middle tier server === To stop a middle tier server that you have console access to, invoke the x or k menu items by typing in that letter and pressing Enter. To stop a middle tier that you don't have console access to, run the following command on the middle tier server as a non-root user in the final_demo/server folder: ./killserver The server is now stopped. If the replication manager is running, then this server will automatically be restarted in the background. If you want to kill a server for good, kill the replication manager first and then kill the servers. === 9. Stopping the replication manager === To stop the replication manager, run the following command on the replication manager server as a non-root user in the final_demo/sacredServer folder: ./killreplicationmanager The replication manager should now be closed. === 10. Stopping the CORBA naming service === To stop the CORBA naming service, run the following command as a non-root user: killall orbd If you want to permanently remove the ORBd's database so that the next invocation of the replication manager won't automatically start up the previously-registered non-faulty servers, then run the following command within the final_demo/sacredServer folder: rm -rf orb.db The CORBA naming service is now stopped. === 11. Stopping the database server === To stop the database server, perform the following steps: 1. Change the current working folder to /tmp/ParkNParkMySQL with the following command: cd /tmp/ParkNParkMySQL 2. Run the MySQL administrative command to shut down the server: ./mysqladmin -u root -p shutdown 3. When prompted for the password, type in the following password and press the return key: procrastinators The database should now be shut down. To remove the database server from /tmp, run the following commands on the database server: cd /tmp rm -rf ParkNParkMySQL The database is now removed from the /tmp filesystem. === 12. Building the project === To build the project from the latest CVS version, run the following command in the final_demo/buildJar folder: ./buildjar If you want to include debugging information in the compiled files, run the following command instead of the one above: ./buildjar-debug These commands will automatically get the latest sources from CVS, compile them, create the jar files, and deploy them to the subfolders in the final_demo folder. === 13. Running one measurement === To run one measurement, run the following command in the final_demo/tests folder: ./runone A list of command line parameters will get displayed to let you know how you can configure the test along with documentation on what each one means. After a test is run, the measurements are copied into a subfolder named test-data-runone. The System.out output from the servers and clients are stored in the output subfolder. Note that before running a data-collection experiment, you should ensure that all servers' /tmp/ParkNPark folders are clear of old log data by running RunOne in "kill only" mode with the following command: ./runone --kill-only To configure which computers are used in the measurements, modify the following files: clients: The clients to use servers: The servers to use sacredserver: The sacred server to use for the replication manager and name service along with the name service's bootstrap port, which should be 7777 unless if the sacredServer/nameservice script was changed Note that the --num-servers and --num-clients parameters will cause RunOne to not use more than those requested numbers by picking sequentially from the clients and servers lists after sorting them alphabetically. === 14. Running all measurements === To run all 48 measurements, run the following command for more information: ./runall Running the entire test suite takes a considerable amount of time, so please be patient.