%FORTUNE{small="yes"}%
Programs Plugin
[ move discussions to ProgramsPluginDev ]
This is a generalization of the (discontinued)
PrologPlugin:
- You can run programs in a somewhat controlled setting
- You can add new tags/programs just by editing this page
- some sanity checking is done at tag usage (args and domains)
- you can use the declared tags also as form ACTIONs by means of the enclosed
doit
script (see DoItExamples)
- you can execute the program at save time and cache its results (see TWiki:Codev/PoorManCache)
- the initialization of the plugin is cached to speed its start-up
Security issues
- Keep this topic protected by properly setting the two lines below:
- BEWARE: the isChrooted feature is NOT YET IMPLEMENTED. The programs are run in the web or in the attachment dir, USE AT YOUR OWN RISK
HOWTO: Defining a new tag/program and its arguments
First you list all the desired tags
- Use capitals (preferred) if you want capitalized tags
- You can deactivate a tag (but leave all its definitions) by just removing it from next line
- Set TAGS = BASH, MAKE, PROLOG, FORTUNE, PDFLATEX
Then you define each tag by editing the table below
- Remember to define the command to be run with all its arguments
- the last column lists argument names, remember to list them! (else they would silently be ignored).
- the command is written
<command> < <stdin>
to define both the command and the stdin formats, else you can use the simpler <command>
syntax
- use
$arg1
... $argn
as placeholders for formatted arguments with names arg1 ... argn, remember to use all of them! (else they would silently be ignored).
- the isChrooted argument IS NOT HONORED YET!, use at your own risk.
... Any other idea? ...
Finally you define each allowed parameter
- Use a table row for each
tag
and arg
, (beware of the case! use the same you used in the tag table above).
- use the format column to define the argument usage
- use
$arg
as a placeholder for the argument value
- use the domain column to restrict the admissible values to a (comma-separated) fixed set
- use the isEnvVar column to declare environment variables
All tags accept also the following (hard-coded) args
Arg |
Default |
isEnvVar |
Format |
Description |
Domain |
when |
view |
no |
|
When the code should be executed |
view, save |
timeout |
5 |
no |
|
Timeout in seconds |
|
format |
$stdout |
no |
|
Format for the replacement string (use $stdout,$stdin,$stderr) |
|
dir |
web |
no |
|
Directory wher the program runs: web or topic (attachment) |
web, topic |
cachedvalue |
|
no |
|
Contains the value cached at save time (do not use) |
|
And then you use it in forms also!
If the plugin is properly installed just press this button! (See also
DoItExamples)
Tips and tricks
- use
when="save"
to run the program at save time and cache the result (this speeds-up the view!)
- use
dir="web"
to run the program in the topic's web
- useful to use other topics as source files ...
- in some cases we are luky, the META tags do not interferes (prolog, make)
- use
dir="topic"
to run the program in the topic's attachments dir
- useful if you want to create attachments reachable with the %ATTACHURL% tag
- use a looooong timeout together with
when="save"
to run long programs and cache the result
Installation
- Use a version of
Plugins.pm
that supports OO-Plugins (attached)
- Install the CPAN
IPC::Run
and Storable
modules.
- Patch
Store.pm
to get rid of <verbatim> tags during beforeSaveHandler (attached)
- You definitely want the TWiki:Plugins/EditTablePlugin to edit the above tables
- Unzip the package in your TWiki dir
- If you like, move the
Plugins/*
files to the TWiki Web
- Activate
ONLY
the tags you need (e.g. the BASH tag is a RISK!)
- protect the ProgramsPlugin topic to avoid improper use
- protect the
doit
script by adding the following lines to bin/.htaccess
<Files "doit">
require valid-user
</Files>
Check if it works
- you will see a fortune cookie at beginning of this page (if
fortune
is installed)
TODO
- Security issues: how to limit malicious usage?
- use chroot/jail (automatic setup and execution)
- use a jailed and virtual environment? (plex86, user-mode-linux, bochs, ...)
- enforce other limits (disk quota, ...)
- do better checks of the definitions read
- restrict specific tags only to specific group of users on a per-web basis
- introduce a TAGS variable at
Web/TWikiPreferences
level
- make a wider usage of 'format' args
- refactor good code to a general Plugin.pm object
- cache of the values computed at initialization
General settings
- Short description of this Plugin
- Set SHORTDESCRIPTION = Runs a command in a slightly controlled environment
- Set to 1 to view the command that would be executed
Examples
Example of a BASH execution
| *stdout* | *stderr* |
%BASH{
code="echo -n 'Hello world from BASH'"
format="| $stdout | $stderr |"
when="save"
}%
%SAVEDBASH{
code="echo -n 'Hello world from BASH'"
format="| $stdout | $stderr |"
when="save"
cachedval="| Hello world from BASH | |"}%
Example of a MAKE execution
%MAKE{
dir="web"
file="MakefileExample.txt"
target="hello"
silent="1"
format="
Output:<font color=blue>$stdout</font>
Errors:<font color=red>$stderr</font>
"
when="save"
}%
%SAVEDMAKE{
dir="web"
file="MakefileExample.txt"
target="hello"
silent="1"
format="
Output:$stdout
Errors:$stderr
"
when="save"
cachedval="
Output:Hello world from MAKE!
Errors:
"}%
Example of GnuProlog execution
%PROLOG{
goal="format('Hello world from Gnuprolog.\n',[])"
when="save"
}%
%SAVEDPROLOG{
goal="format('Hello world from Gnuprolog.\n',[])"
when="save"
cachedval="Hello world from Gnuprolog.
"}%
Example of timed-out processes
%SAVEDBASH{
code="for ((I=1;I<100;I++)) ; do sleep 1 ; echo 'Hello BASH World!' ; done"
when="save"
cachedval="Hello BASH World!
Hello BASH World!
Hello BASH World!
Hello BASH World!
Hello BASH World!
BASH process timed out after 5 seconds."}%
%SAVEDPROLOG{
goal="repeat,sleep(1),format('Hello world from Gnuprolog.\n',[]),fail"
when="save"
cachedval="Hello world from Gnuprolog.
Hello world from Gnuprolog.
Hello world from Gnuprolog.
Hello world from Gnuprolog.
Hello world from Gnuprolog.
PROLOG process timed out after 5 seconds."}%
Plugin Info
--
TWiki:Main.AndreaSterbini - 06 Sep 2003