ocPortal Tutorial: OcCLE
Written by Philip Withnall, ocProductsOcCLE, the ocPortal Command-Line Environment, is designed for experienced system administrators who find command-lines faster to use than GUI-based alternatives.
We designed OcCLE to supplement the features of the Admin Zone, rather than to replace them. The interface allows you to enter commands in the form of:
- PHP code
- SQL database queries
- OcCLE-code scripts
- OcCLE-code commands, which you can use to fully interact with the OcCLE meta-filesystem
Table of contents
CommandsAlthough the system is very flexible, there are many commands to use, designed for interaction with the meta-filesystem and other systems designed specifically for OcCLE. Since UNIX is the grandfather of almost all of the operating systems where command-line use is most prevalent – and administrators comfortable with command-lines will probably be UNIX experts – many of the commands mirror their UNIX counterparts.
The basic format for a command is as follows:
command_name -o -long_option -o2=value -long_option2="value 2" parameter1 "parameter 2" parameter3
- A command name (no spaces)
- followed by a list of options (either in short or long format; this is decided by the command in question) with optional values (quoted if they contain spaces)
- then a list of parameter values (quoted if they contain spaces).
OcCLE supports backslashing, so you can escape any quotes in values you're passing:
echo "Grandma said: \"Hello world!\""
For a full list of OcCLE commands, simply execute the commands command in OcCLE:
PHP codePHP can be entered and executed by OcCLE, simply by prefixing the code to be executed with a colon (":"). The returned data will be displayed as best as possible (its type will be determined and outputted as appropriate). Multiple PHP commands may be executed (separated by semi-colons, as per normal PHP code).
:echo "Hello"; echo " World.";
OcCLE will attempt to store variables and included files between command requests (using a cookie) to make it possible to execute command sequences without having to put them all on one line.
There is a memory limit of 4k for this, to avoid causing slow downs in requests and hitting maximum cookie size limits.
SQL queriesSQL queries can also be executed by OcCLE, simply by prefixing the query to be executed with an 'at' symbol ("@"). As with PHP commands, the query results will be outputted in an appropriate manner.
Separating multiple queries using semicolons is not supported.
Even though OcCLE commands are single-line, pasting multi-line commands in usually works. The only exception would be if the line breaks are a part of strings within the query, in which case they would end up replaced by spaces.
You are allowed to do non-read queries, such as INSERTs and DELETEs, but you'll be told "Error: Your search yielded no results.". Ignore that, it's just a generic messages to tell you explicitly that no results were shown.
Meta-filesystemsOne of the main features of OcCLE is the fact that various facets of ocPortal can be manipulated through meta-filesystems. There are several included by default, but it is quite simple to write more as hooks if you know how to program. There are several different meta-filesystems for accessing the real file structure of the ocPortal installation, one for manipulating members (if you have OCF installed), one for manipulating the database, and a couple of others.
To use these meta-filesystems, simply navigate around using the standard UNIX filesystem commands (cd, pwd, ls, etc.), and modify files in a similar fashion to change the appropriate behind-the-scenes value.
Each of the default meta-filesystems is mapped to a subdirectory of the OcCLE meta-root directory, with obvious mappings sometimes inspired by UNIX. These mappings are stored in an array in sources/occle.php, and if you know how to program you can easily change and customise the mappings to personalise your OcCLE installation.
The default meta-filesystems are as follows, and are all mapped as subdirectories of the root directory:
- bin: A place to store all your OcCLE scripts
- database: Access to the raw SQL database
- etc: Access to ocPortal configuration options
- home: Access to the filedump
- members: A listing of every member registered on the system, with their preferences and usergroups
- raw: A raw listing of the actual ocPortal installation directory
- root: A listing of the ocPortal installation directory, taking source code overrides into account
ScriptsCommands can be put together in scripts and saved for later use in the bin filesystem. These can be executed on the OcCLE command-line just by entering the name of the script, or can alternatively be scheduled for execution by the calendar to run at some point in the future (possibly routinely).
Running from a normal operating system command promptOcCLE can tie directly into your operating system shell. For example, on Linux you can start it up with:
OcCLEchatThe final feature of OcCLE is OcCLEchat, which allows users of OcCLE to chat with each other across the internet. It is used via the occlechat command, taking a website URL and message as parameters (remember to double-quote them if they contain spaces). The system is designed to be resistant to intrusions, as each message's validity is checked before it is displayed.
OcCLEchat is designed to allow website administrators to communicate with each other and share tips, tricks and experiences with ocPortal.