# Remote.pm: Remote Collection Package

package RDA::UI::Remote;

# $Id: Remote.pm,v 1.14 2015/05/08 18:17:03 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/UI/Remote.pm,v 1.14 2015/05/08 18:17:03 RDA Exp $
#
# Change History
# 20150424  MSC  Introduce the control agent concept.

=head1 NAME

RDA::UI::Remote - Remote Collection Package

=head1 SYNOPSIS

 <rda> <options> -XRemote <command> <switches> <arg> ...

 <sdci> <options> -XRemote <command> <switches> <arg> ...

=head1 DESCRIPTION

The following commands are available:

=cut

use strict;

BEGIN
{ use Exporter;
  use IO::File;
  use RDA::Text qw(get_string);
  use RDA::Options;
  use RDA::Object::Message;
  use RDA::Object::Rda qw($CREATE $FIL_PERMS);
}

# Define the global public variables
use vars qw($STRINGS $VERSION @ISA);
$VERSION = sprintf('%d.%02d', q$Revision: 1.14 $ =~ /(\d+)\.(\d+)/);
@ISA     = qw(Exporter);

# Define the global private constants

# Define the global private variables

# Report the package version
sub Version
{ return $VERSION;
}

=head2 S<authenticate [-t file]>

This commands submits requests received on its standard input to the SSH
authentication agent and returns agent response on its standard output.

=cut

sub authenticate
{ my ($agt, @arg) = @_;
  my ($ctl, $log, $opt, $trc);

  # Treat the switches
  $opt = RDA::Options::getopts('t:', \@arg);
  $trc = undef unless defined($log = RDA::Object::Rda->is_path($opt->{'t'}))
    && ($trc = IO::File->new)->open($log, $CREATE, $FIL_PERMS);

  # Treat the requests
  eval {
    # Initialize the interface with the authentication agent
    require RDA::Driver::SshAgent;
    $ctl = RDA::Driver::SshAgent->new($trc);

    # Treat the requests
    binmode(STDIN);
    binmode(STDOUT);
    $ctl->treat_request while $ctl->get_request;
    };
  if ($@)
  { $trc->syswrite($@, length($@)) if $trc;
    return 3;
  }

  # Close the interface and the trace file
  $ctl->delete_object if $ctl;
  $trc->close         if $trc;

  # Indicate a successful completion
  return 0;
}

=head2 S<disable [-a|node...]>

This command disables the remote collection on nodes that are still executing a
step before the post treatment or the report package transfer. It supports the
following switches and arguments:

=over 9

=item B<  -a>

Applies the action on all nodes.

=item B<  node>

Applies the action on specified nodes.

=back

=cut

sub disable
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the options
  $opt = RDA::Options::getopts('a', \@arg);

  # Perform the action and indicate the completion status
  return $agt->submit(q{.}, 'REMOTE.DISABLE',
    all       => $opt->{'a'},
    nodes     => (scalar @arg) ? [@arg] : undef);
}

=head2 S<dispatch [-e request]>

This command treats all messages received on the standard input and puts their
responses on the standard output. It supports the following switch:

=over 14

=item B<  -e request>

Specifies the closing request (C<REMOTE.EXIT> by default).

=back

=cut

sub dispatch
{ my ($agt, @arg) = @_;
  my ($end, $opt, $ret);

  # Treat the options
  $opt = RDA::Options::getopts(q{e:}, \@arg);
  $end = (exists($opt->{'e'}) && $opt->{'e'} =~ m/^\w+\.\w*$/)
    ? $opt->{'e'}
    : 'REMOTE.EXIT';

  # Execute all commands received
  eval {
    require RDA::Driver::Agent;
    $ret = RDA::Driver::Agent->treat_messages($agt, $end);
    };

  # Indicate the completion status
  return $@ ? 3 : $ret;
}

=head2 S<edit -e key=val[,...] [-a|node...]>

This command edits one or more remote node initial settings. It supports the
following switches and arguments:

=over 18

=item B<  -a>

Applies the action on all nodes.

=item B<  -e key=val,...>

Specifies the modifications as a comma separated list of C<key=value> pairs. No
settings are created.

=item B<  node>

Applies the action on specified nodes.

=back

=cut

sub edit
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the options
  $opt = RDA::Options::getopts('ae*', \@arg);

  # Perform the action and indicate the completion status
  return $agt->submit(q{.}, 'REMOTE.EDIT',
    all       => $opt->{'a'},
    edit      => $opt->{'e'},
    nodes     => (scalar @arg) ? [@arg] : undef);
}

=head2 S<help>

This command displays the command syntax and the related explanations.

=cut

sub help
{ return shift->submit(q{.}, 'DISPLAY.DSP_POD', package => __PACKAGE__);
}

=head2 S<list [-f]>

This command lists the nodes. It supports the following switch:

=over 9

=item B<  -f>

Includes connection status.

=back

=cut

sub list
{ my ($agt, @arg) = @_;
  my ($buf, $opt, $rsp);

  # Treat the options
  $opt = RDA::Options::getopts('f', \@arg);

  # Perform the action and indicate that there are no setup changes
  $rsp = $agt->submit(q{.}, 'REMOTE.LIST',
    description => 1,
    full        => $opt->{'f'});

  # Display the report and indicate the completion status
  return $agt->submit(q{.}, RDA::Object::Message->new('DISPLAY.DSP_REPORT',
    page => 1)->add_data(($buf = $rsp->get_data)
      ? q{.M 4 '}.get_string('Nodes').qq{'\n}.$buf.qq{\n}
      : q{.T'}.get_string('NoNodes').qq{'\n}));
}

=head2 S<restart [-a|node...]>

This command restarts the remote node collection from the beginning. This occurs
only when the node step is defined already. It supports the following switches
and arguments:

=over 9

=item B<  -a>

Applies the action on all nodes.

=item B<  node>

Applies the action on specified nodes.

=back

=cut

sub restart
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the options
  $opt = RDA::Options::getopts('a', \@arg);

  # Perform the action and indicate the completion status
  return $agt->submit(q{.}, 'REMOTE.RESTART',
    all       => $opt->{'a'},
    nodes     => (scalar @arg) ? [@arg] : undef);
}

=head2 S<retry [-a|node...]>

This command attempts to execute the last step of remote data collections
again. This is performed for nodes with errors only. It supports the following
switches and arguments:

=over 9

=item B<  -a>

Applies the action on all nodes.

=item B<  node>

Applies the action on specified nodes.

=back

=cut

sub retry
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the options
  $opt = RDA::Options::getopts('a', \@arg);

  # Perform the action and indicate the completion status
  return $agt->submit(q{.}, 'REMOTE.RETRY',
    all       => $opt->{'a'},
    nodes     => (scalar @arg) ? [@arg] : undef);
}

=head2 S<set [-a] type [node...]>

This command specifies the commands that should be used for remote operations
on the specified nodes. It supports the following switches and arguments:

=for stopwords remsh rsh ssh

=over 9

=item B<  -a>

Applies the action on all nodes.

=item B<  node>

Applies the action on specified nodes.

=item B<  type>

Specifies the connection type. It supports the following types:

=over 11

=item S<  C<default>>

Restores the default settings.

=item S<  C<remsh>>

Uses F<remsh> and F<rcp>.

=item S<  C<rsh>>

Uses F<rsh> and F<rcp>.

=item S<  C<ssh>>

Uses F<ssh> and F<scp>.

=item S<  C<ssh0>>

Uses F<ssh> and F<scp> without connection timeout.

=back

=back

=cut

sub set
{ my ($agt, @arg) = @_;
  my ($opt, $typ);

  # Treat the options
  $opt = RDA::Options::getopts('a', \@arg);

  # Perform the action and indicate the completion status
  $typ = shift(@arg);
  return $agt->submit(q{.}, 'REMOTE.SET',
    all       => $opt->{'a'},
    nodes     => (scalar @arg) ? [@arg] : undef,
    type      => $typ);
}

=head2 S<suspend [-a|node...]>

This command suspends remote collection by putting the current step in
error. This is only performed for nodes where the collection is not
completed. It supports the following switches and arguments:

=over 9

=item B<  -a>

Applies the action on all nodes.

=item B<  node>

Applies the action on specified nodes.

=back

=cut

sub suspend
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the options
  $opt = RDA::Options::getopts('a', \@arg);

  # Perform the action and indicate the completion status
  return $agt->submit(q{.}, 'REMOTE.SUSPEND',
    all       => $opt->{'a'},
    nodes     => (scalar @arg) ? [@arg] : undef);
}

=head1 REMOTE DAEMON MANAGEMENT

=head2 S<start [-a|node...]>

This command starts a background collection on the specified nodes. It supports
the following switches and arguments:

=over 9

=item B<  -a>

Applies the action on all nodes.

=item B<  node>

Applies the action on specified nodes.

=back

=cut

sub start
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the options
  $opt = RDA::Options::getopts('a', \@arg);

  # Perform the action and indicate the completion status
  return $agt->submit(q{.}, 'REMOTE.START',
    all       => $opt->{'a'},
    nodes     => (scalar @arg) ? [@arg] : undef);
}

=head2 S<stop [-a|node...]>

This command stops the background collection on the specified nodes. It
supports the following switches and arguments:

=over 9

=item B<  -a>

Applies the action on all nodes.

=item B<  node>

Applies the action on specified nodes.

=back

=cut

sub stop
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the options
  $opt = RDA::Options::getopts('a', \@arg);

  # Perform the action and indicate the completion status
  return $agt->submit(q{.}, 'REMOTE.STOP',
    all       => $opt->{'a'},
    nodes     => (scalar @arg) ? [@arg] : undef);
}

1;

__END__

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::Driver::Agent|RDA::Driver::Agent>,
L<RDA::Driver::SshAgent|RDA::Driver::SshAgent>,
L<RDA::Object|RDA::Object>,
L<RDA::Object::Message|RDA::Object::Message>,
L<RDA::Object::Rda|RDA::Object::Rda>,
L<RDA::Options|RDA::Options>,
L<RDA::Request::DISPLAY|RDA::Request::DISPLAY>,
L<RDA::SDCL::Block|RDA::SDCL::Block>,
L<RDA::SDCL::Language|RDA::SDCL::Language>,
L<RDA::SDSL::Module|RDA::SDSL::Module>,
L<RDA::Text|RDA::Text>

=head1 COPYRIGHT NOTICE

Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.

=head1 TRADEMARK NOTICE

Oracle and Java are registered trademarks of Oracle and/or its
affiliates. Other names may be trademarks of their respective owners.

=cut