further detail OR->connect arguments, and document other bits

[scpubgit/Object-Remote.git] / lib / Object / Remote / Connector / LocalSudo.pm

diff --git a/lib/Object/Remote/Connector/LocalSudo.pm b/lib/Object/Remote/Connector/LocalSudo.pm
index e9bbb96..b04a571 100644 (file)
--- a/lib/Object/Remote/Connector/LocalSudo.pm
+++ b/lib/Object/Remote/Connector/LocalSudo.pm
@@ -1,5 +1,6 @@
 package Object::Remote::Connector::LocalSudo;
 
+use Object::Remote::Logging qw (:log :dlog);
 use Symbol qw(gensym);
 use Module::Runtime qw(use_module);
 use IPC::Open3;
@@ -68,7 +69,7 @@ sub _start_perl {
                       if (sysread($sudo_stderr, my $buf, 32768) > 0) {
                         log_trace { "LocalSudo: successfully read data, printing it to STDERR" };
                         print STDERR $buf;
-                        log_trace { "LocalSudo: print() to STDERR is done" };                   
+                        log_trace { "LocalSudo: print() to STDERR is done" };
                       } else {
                         log_debug { "LocalSudo: received EOF or error on file handle, unwatching it" };
                         Object::Remote->current_loop
@@ -96,3 +97,38 @@ push @Object::Remote::Connection::Guess, sub {
 };
 
 1;
+
+=head1 NAME
+
+Object::Remote::Connector::LocalSudo - A connector for a local Perl process with
+sudo
+
+=head1 DESCRIPTION
+
+Used to create a connector that talks to a Perl process started on the local
+machine, via sudo as a specific user. Invoked by L<Object::Remote/connect> if
+the connection spec is a username followed by a @.
+
+=head1 ARGUMENTS
+
+Inherits arguments from L<Object::Remote::Connector::Local> and provides the
+following:
+
+=head2 target_user
+
+When invoked via L<Object::Remote/connect>, specified via the connection spec,
+and not overridable.
+
+The name of the user to run the process as.
+
+=head2 password_callback
+
+A function that returns the password to be passed on to sudo. Defaults to asking
+the operator via command line.
+
+=head2 sudo_perl_command
+
+An arrayref containing a list of strings to be passed to L<IPC::Open3> to open
+the perl process. Defaults to a specific sudo incantation.
+
+=cut