restructuring of boca's git

1 files changed, 128 insertions, 0 deletions

diff --git a/doc/AUTOJUDGING.txt b/doc/AUTOJUDGING.txt
new file mode 100644
index 0000000..cf81f06
--- /dev/null
+++ b/doc/AUTOJUDGING.txt
@@ -0,0 +1,128 @@
+(Last updated 18/oct/2011 by cassio@ime.usp.br. See copyright notice below.)
+
+AUTOJUDGING.txt
+---------------
+
+To help the process of judging, the BOCA system provides
+a php script that is able to execute some user defined
+script in order to compile, execute and compare the output
+generated by teams with the correct output. This procedure
+is not essential to the system, since each judge is capable
+to download from BOCA all the files needed to evaluate a
+submission.
+
+The propose here is not to have a automated scheme for
+submission evaluation, but a supporting system that can
+help judges to do their job. In this way, the autojudging
+provides to the judge the data generated by the scripts
+when trying to compile, to execute and to compare the results.
+This data is presented in a formatted way during the judging 
+process inside the BOCA web interface, and can help the
+judge to evaluate the submission. If the autojudging is
+not enabled in the contest, the judges will see just some
+"unavailable" texts when judging a submission, and they
+will have to execute the whole process by theirselves.
+
+To start the autojudging procedure, the only thing needed
+is to run the autojudging.php script from some commandline
+shell. Note that it may be necessary to change the permissions
+of private/conf.php file to something more readable and the php.ini
+file to turn safe_mode off (on the computer running the
+autojudging scheme). Furthermore, verify whether the private/conf.php
+options are correctly pointing to the postgresql server/users
+and if the current working directory (ie, ".") is included 
+in the PATH environment variable.
+
+$ sudo /bin/bash
+# cd /var/www/boca/src
+# /var/www/boca/tools/autojudge.sh
+
+The autojudging.php will stay running until CRTL+C is
+pressed or it's killed by some other way. Autojudging waits 
+for a new submission, takes it and executes the
+compiling/running/comparing scripts defined in BOCA for the
+corresponding language/problem (this information is all included
+in the problem package for each problem). More details about them
+are in the ADMIN.txt file and in the examples of the folder
+doc/problemexamples/
+
+As long as the autojudging php script will execute
+code from teams, these codes may contain malicious
+procedures. Thus it is essential that a dedicated
+computer be allocated only for the autojudging
+scheme. Furthermore, users with shell on this computer
+could eventually see important data which they should not
+be allowed. This computer must have the same requirements
+as the one running the BOCA web interface (but it
+does not need postgresql neither a running web server), 
+and it needs to be configured properly. All the steps
+described in INSTALL.txt applies to this new computer,
+but three important things should be noted:
+
+(ATTENTION: IF YOU ARE USING THE ICPC LINUX VIRTUAL
+MACHINE, THEN ALL THE FOLLOWING SHOULD ALREADY
+BE DONE FOR YOU...)
+
+1) the computer must have a firewall that
+only permits connections between it and the main BOCA 
+server (this is an important security issue). This is automatically
+done if you are using the ICPC linux virtual machine, which is in fact
+the best way to run the autojudging system.
+
+2) the src/private/conf.php file must be configure properly
+with the correct location of the boca database
+(probably it will be needed tcp/ip connection to
+the postgresql at the main BOCA server), the
+correct user/password for database access, the
+local IP number and the current contest number.
+
+3) the postgresql running at the main BOCA server
+will have to be configured to accept connections
+from the IP of the autojudging server. This can
+be achieved inserting the line
+
+host  all  all  IPAUTOJUDGING  255.255.255.255  md5
+
+in the pg_hba.conf file at the main BOCA server, where IPAUTOJUDGING
+is to be replaced by the actual IP of the computer running the
+autojudging script. Note that if run within a virtual machine, one
+must take the IP of the host computer, not of the virtual machine for
+this configuration. If the postgresql server is already configured to
+accept incoming connections from all IPs, then this is not necessary.
+
+Talking a little bit more about the compiling/running
+script, it will be responsible for running the executable
+code generated from the team's source. This is exactly
+where the danger lives. To decrease the risk and to have
+control over the time spent by the team's code, the C
+source code safeexec.c (tools directory) should be used. 
+It was designed to execute other programs with lower 
+privilegies and with a time limit set. It is enough to 
+run "gcc -O2 -o safeexec safeexec.c" for compiling and it is 
+necessary to make a setuid root: "chown root.root safeexec" 
+and "chmod 4555 safeexec" for running. This safeexec must be 
+placed in a folder included in the path, usually copying it to
+/usr/bin will suffice: "cp -a safeexec /usr/bin" (note the -a)
+
+
+Contacts and Copyrights
+-----------------------
+BOCA Copyright (c) 2003- Cassio Polpo de Campos (cassio@ime.usp.br)
+http://www.ime.usp.br/~cassio/boca
+
+////////////////////////////////////////////////////////////////////////////////
+//BOCA Online Contest Administrator
+//    Copyright (C) 2003-2012 by BOCA Development Team (bocasystem@gmail.com)
+//
+//    This program is free software: you can redistribute it and/or modify
+//    it under the terms of the GNU General Public License as published by
+//    the Free Software Foundation, either version 3 of the License, or
+//    (at your option) any later version.
+//
+//    This program is distributed in the hope that it will be useful,
+//    but WITHOUT ANY WARRANTY; without even the implied warranty of
+//    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//    GNU General Public License for more details.
+//    You should have received a copy of the GNU General Public License
+//    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+////////////////////////////////////////////////////////////////////////////////