runcommand plugin

This plugin executes a program on the fly and shows its output.

You can use it to generate reports from the system or to execute some administration steps.

For example, I use it to collect information from my enterprise servers (free space on disks, hardware status, etc.)

• 28 nov 2009: Added Custom text for submit button, move function prepareCommand to postaction to increase security. Add debug option to plugin configuration from the DokuWiki panel, rebuild of postaction as class.
• 20 sep 2009: Added Custom text and hidden value for cancel button
• 19 aug 2009: Added Custom text button from Steve (many Thanks)
• 26 mar 2009: Add French translation, many thanks to its author, Etienne M.
• 25 mar 2009: Runcommand released.

It's quite easy:

• download this archive and unpack it in the /lib/plugins directory of your wiki or use the plugin manager page from admin menu (URL: http://sites.google.com/site/aelsantex/archivio/runcommand.tgz?attredirects=0&d=1).

• Create directory scripts under wiki installation and set it into script_dir field of runcommand section under wiki configuration page. As the default, I choose to put dir under DOKUWIKI_ROOT/data/scripts. See configuration for more details.

Syntax is simple:

<runcommand>
command|<command>
outputType|<output type>
runButtonText|<run button label>
cancelButtonText|{ <cancel button label> | none }
<arg-1 label>|<arg type>=<arg value>
…
<arg-n label>|<arg type>=<arg value>
</runcommand>

Where:

• <command>: The command invocation. You can use the same syntax used into a CLI interface to run the program. You can pass some arguments and keep argument values from runcommand arguments. Keep in mind that the arguments are referred by its label preceded by dollar char ($) and the space substituted with underscore (see next example, refer $arg_1 into command, it matches with <arg-1 label> arg 1). See configuration for security details.

• <output type>: One of the next values:
  • text: If the program writes its output in text format.
  • html: If the program writes its output in HTML format.
  • wiki: If the program writes its output in DokuWiki format (output is rendered before its visualizations).
  • choice: The user may choose one of the previous formats from a select field.

• <arg-X label>: The label is printed before the argument field and the name of the argument for it is used as the command argument.

• <arg type>: One of the next values:
  • text: If you want a text field for the argument.
  • hidden: Generate a hidden field. If you use a hidden field, the label isn't printed.
  • list: Generate a selectable list of values.

• <arg value>: The default value for a text and an hidden field. The list of available value for a list. If you use a list you must respect this syntax:
  list=<item 1>:label 1;<item N>:<label N>
  Where:
  • <item X>: Is the value given by the list as argument.
  • <label X>: Is the label that the user sees in the list.

Example:

In this example, I use the printf command to show the values of arguments.

<runcommand>
command|printf "==== Test ====\n\n__Result__\n\n  * arg1=**$arg_1**\n  * arg2=//$arg_2//\n  * arg3=$arg_3\n\n <note>Work</note>"
cancelButtonText|{ <cancel button label> | none }
arg 1|text=argument 1
arg 2|hidden=argument 2
arg 3|list=item 1:value 1;item 2:value 2;item 3:value 3;default:item 2
</runcommand>

In this example I use the printf command to show the values of arguments without display the cancel button and with custom label for run button

<runcommand>
command|printf "==== Test ====\n\n__Result__\n\n  * arg1=**$arg_1**\n  * arg2=//$arg_2//\n  * arg3=$arg_3\n\n <note>Work</note>"
runButtonText|Test Me
cancelButtonText|none
outputType|wiki
arg 1|text=argomento 1
arg 2|text=argomento 2
arg 3|list=item 1:value 1;item 2:value 2;item 3:value 3;default:item 2
</runcommand>

From wiki configuration's page you find five fields dedicated to runcommand.

• safe_scripts: If this is checked, the program must be in the script_dir directory. I suggest to keep it checked for security reason. Think about an rm -rf / command….

• script_dir: specify the directory where the programs are located. As a convention, I suggest using folder scripts under DOKUWIKI_ROOT/data directory.

• syntax_debug: Enable the debug (you can choice 4 level of debug) of syntax page.

• postaction_debug: Enable the debug (you can choice 4 level of debug) of postaction page. May be help for debug external command execution

• debug_log: File,with full path, where write the debug messages.

Actually, runcommand supports only Italian and English languages. I'm really happy if anyone could contribute to the translation in other languages… ;)

Write here if you find a bug.

Some points to consider:

• Hard coded path in postaction.php FIXED !
• If you are using RewriteRules in Apache, or some other settings that convert slashes into underscores, the postaction.php scrip may not get called. → Yes, but is necessary to use the space into label, a possible solution may be dissociate the label from the name of the argument, but this choice increase the difficult of plugin syntax.
• Ensure that CSS and JavaScript compression is off when using jQuery.

– Chris Usher

• — Etienne M. 25/03/2009 11:27 Hi! Not sure I will use your plugin, but here are the french language files:
  • fr/lang.php

    <?php
    /**
     * French language file
     *
     * @author     Alessandro Celli <aelsantex@gmail.com>
     * @author     Etienne M. <emauvaisfr@yahoo.fr>
     */
     
    // custom language strings for the plugin
     
    $lang['btn_submit']   = 'Ex&eacute;cuter';
    $lang['btn_reset']   = 'Effacer';
    $lang['lbl_outputFormat'] = 'Format de sortie ';
    $lang['fld_text'] = 'Texte';
    $lang['fld_wiki'] = 'Wiki';
    $lang['fld_html'] = 'Html';
    $lang['msg_wrongsyntax'] = 'Mauvaise syntaxe pour le plugin runcommand.';

  • fr/settings.php

    <?php
    /**
     * French language file
     *
     * @author Alessandro Celli <aelsantex@gmail.com>
     * @author     Etienne M. <emauvaisfr@yahoo.fr>
     */
     
    // for the configuration manager
     
    $lang['safe_scripts'] = 'N\'ex&eacute;cuter que les scripts pr&eacute;sents dans le dossier des scripts autoris&eacute;s.';
    $lang['script_dir']  = 'Dossier qui contient les scripts autoris&eacute;s (&agrave; partir de la racine du dokuwiki).';

Hi Etienne, many thanks, I have included your translation but now I have introduced other 3 parameters. Can you help me to translate that?

• — Mailgifson

Can you give a simple script to test?
I can not use this plug-in :S

Ok, a little example for linux/unix users.. Save the follow script into scripts directory as printf with execution permissions (rwxr–r–) and try to use given examples:

printf

#!/bin/bash
 printf "$*\n"