--- /dev/null
+<article xmlns='http://docbook.org/ns/docbook'>
+ <title>koha-shell</title>
+ <info>
+ <productname>Koha</productname> is the first free software library automation package.
+ <author>
+ <personname>
+ <firstname>Robin</firstname>
+ <surname>Sheat</surname>
+ </personname>
+ <affiliation>
+ <orgname>Catalyst IT</orgname>
+ <uri>http://www.catalyst.net.nz</uri>
+ </affiliation>
+ <contrib>Author</contrib>
+ </author>
+ </info>
+
+ <refentry xml:id="koha-shell">
+
+ <refmeta>
+ <refentrytitle>koha-shell</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>koha-shell</refname>
+ <refpurpose>Gives you a shell with the user and environment set to make it easy to do koha operations.</refpurpose>
+ <refclass>UNIX/Linux</refclass>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>koha-shell</command>
+ <arg><option>--command|-c</option> COMMAND</arg>
+ <arg><option>--help|-h</option></arg>
+ <arg><option>--login|-l</option></arg>
+ <arg><option>--preserve-environment|-p|-m</option></arg>
+ <arg><option>--shell|-s</option> SHELL</arg>
+ <arg><option>--verbose|-v</option></arg>
+ <arg choice="req" rep="norepeat"><replaceable>instancename</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1><title>Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--command</option></term>
+ <listitem>
+ <para>Run the specified command rather than launching a shell.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--help</option></term>
+ <listitem>
+ <para>Show a usage synopsis.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--login</option></term>
+ <listitem>
+ <para>Make the shell a login shell.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--preserve-environment</option></term>
+ <listitem>
+ <para>Preserve the current environment (note that if you run it through 'sudo', this may not work as you'd expect.)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--shell</option></term>
+ <listitem>
+ <para>Run the specified shell. The default is the shell of the current environment, followed by /bin/sh.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--verbose</option></term>
+ <listitem>
+ <para>Show the command that is going to be run.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1><title>Description</title>
+ <para>This launches a shell with the user and required environment variables set in such a way that running any Koha commands will
+ work correctly. With the use of '-c', it can be used to easily run commands in the correct environment.</para>
+ <para>It behaves mostly as a wrapper for <command>su(1)</command>, so a deeper discussion of the options can be found in there.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+ <para>
+ To get a shell:
+ </para>
+ <para><command>$ sudo koha-shell library</command></para>
+ <para>
+ To run a command:
+ </para>
+ <para><command>$ sudo koha-shell -c "/usr/share/koha/bin/migration_tools/bulkmarcimport.pl -b -file data.marc" library</command></para>
+ </refsect1>
+
+ <refsect1><title>See also</title>
+ <simplelist type="inline">
+ <member><command>koha-foreach(8)</command></member>
+ <member><command>su(1)</command></member>
+ </simplelist>
+ </refsect1>
+
+ </refentry>
+
+</article>
--- /dev/null
+#!/usr/bin/perl
+# koha-shell -- put you in a shell with a koha environment set up
+# Copyright 2012 Catalyst IT, Ltd
+#
+# 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/>.
+
+use Getopt::Long;
+use Modern::Perl;
+
+Getopt::Long::Configure("bundling");
+
+my %opts;
+my $res = GetOptions( \%opts, "command|c=s", "help|h", "login|l", "shell|s=s",
+ "preserve-environment|p|m", "verbose|v" );
+
+if ( !$res || $opts{help} ) {
+ show_help( !$res );
+ exit( !$res );
+}
+
+if ( !@ARGV ) {
+ show_help( 1, "An instance name must be supplied." );
+ exit(1);
+}
+my $instance = shift @ARGV;
+if ( !-e "/etc/koha/sites/$instance" ) {
+ show_help( 1, "The instance doesn't exist: $instance" );
+ exit(1);
+}
+my $shell = $opts{shell} || $ENV{SHELL} || '/bin/sh';
+
+# Now we're set up, build the 'su' command
+my @su_args;
+push @su_args, '/bin/su';
+push @su_args, '--preserve-environment' if $opts{'preserve-environment'};
+push @su_args, '--login' if $opts{login};
+push @su_args, '--command',
+ "env "
+ . "KOHA_CONF=/etc/koha/sites/$instance/koha-conf.xml "
+ . "PERL5LIB=/usr/share/koha/lib $shell"
+ . ( $opts{command} ? " -c '$opts{command}'" : '' );
+push @su_args, "$instance-koha";
+
+print "Command: '".join("' '",@su_args)."'\n" if $opts{verbose};
+system(@su_args);
+if ( $? == -1 ) {
+ print STDERR "failed to execute: $!\n";
+}
+elsif ( $? & 127 ) {
+ printf STDERR "child died with signal %d, %s coredump\n",
+ ( $? & 127 ), ( $? & 128 ) ? 'with' : 'without';
+}
+
+sub show_help {
+ my ( $err, $msg ) = @_;
+
+ my $fh = $err ? *STDERR : *STDOUT;
+ say $fh "Error: " . $msg if $msg;
+ print $fh $_ while <DATA>;
+}
+
+__DATA__
+koha-shell -- gives you a shell with your Koha environment set up
+
+Usage: koha-shell [options] [instance name]
+
+Options:
+ -c, --command COMMAND pass COMMAND to the invoked shell
+ -h, --help show this help and quit
+ -l, --login make the shell a login shell
+ -m, -p,
+ --preserve-environment do not reset environment variables
+ -s, --shell SHELL use SHELL instead of the one from your environment
+ -v, --verbose output the full command that will be executed
+
+The default shell is the one currently in use. Refer to su(1) for more detail
+on these options.