Merge branch 'manpage' into 'master'

Added awit-ssh manpage

See merge request !27

Makefile.PL

 # Makefile
-# Copyright (C) 2014-2016, AllWorldIT
+# Copyright (C) 2014-2017, AllWorldIT
 #
 # 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
@@ -25,5 +25,10 @@ WriteMakefile(
 	VERSION_FROM => "awit-ssh",
 
 	EXE_FILES => [qw( awit-ssh )],
+
+	MAN1PODS => {
+		'awit-ssh' => 'blib/man1/awit-ssh.1',
+	},
+
 );
 

awit-ssh

 #!/usr/bin/perl
 # awit-ssh - SSH initiator which searches LDAP for host details
-# Copyright (c) 2016, AllWorldIT
+# Copyright (c) 2016-2017, AllWorldIT
 #
 # 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
@@ -15,11 +15,33 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+
+
+=encoding utf8
+
+=head1 NAME
+
+awit-ssh - LDAP lookup utility for SSH hosts.
+
+=head1 SYNOPSIS
+
+	awit-ssh < HOST[:PORT]] [--libvirt-vnc HOST:PORT] [--knock HOST:PORT] | --rsync -- remote://[HOST[:PORT]]/full/path DEST >
+
+=cut
+
+=head1 DESCRIPTION
+
+awit-ssh perl script that automates connecting to a server via ssh by looking up the user and port information from a LDAP
+database.
+
+=cut
+
+
+
 use strict;
 use warnings;
 
 
-
 use Term::ANSIColor;
 use Getopt::Long;
 use Net::DBus qw(:typing);
@@ -54,17 +76,35 @@ use User::pwent;
 
 
 my $NAME = "AWIT-SSH-Client";
-our $VERSION = "0.8.2";
+our $VERSION = "0.8.3";
+
 
+print(STDERR "$NAME v$VERSION - Copyright (c) 2016-2017, AllWorldIT\n\n");
 
-print(STDERR "$NAME v$VERSION - Copyright (c) 2016, AllWorldIT\n\n");
 
+=head1 OPTIONS
+
+C<awit-ssh> provides the below commandline options...
+
+=cut
 
 
 # Grab options
 my %optctl = ();
 GetOptions(\%optctl,
+
+=head2 --help|?
+
+	Display this help information.
+
+=cut
 	"help|?",
+
+=head2 --version
+
+	Display version information.
+
+=cut
 	"version",
 
 	# TODO: debug is not implemented, make sure displayHelp is updated
@@ -73,10 +113,25 @@ GetOptions(\%optctl,
 	# TODO: Improve globbing before adding it to displayHelp
 	"globbing",
 
+=head2 --knock <HOST:PORT>
+
+	Knock on HOST:PORT to gain access.
+
+=cut
 	"knock=s",
 
+=head2 --rsync remote://<HOST[:PORT]>/full/path DEST
+
+	Use rsync to rsync data from remote server to DEST. This can be specified either way around.
+
+=cut
 	"rsync",
 
+=head2 --libvirt-vnc <HOST:PORT>
+
+	Connect to remote VNC server HOST:PORT.
+
+=cut
 	"libvirt-vnc=s",
 ) or exit 1;
 
@@ -179,6 +234,13 @@ my $realLoginHost = $loginHost;
 my ($forwardHost,$forwardPort,$forwardUsername,@forwardPortExtra);
 
 
+=head1 CONFIG FILE
+
+The following options are read from C<~/.awit-ssh.conf>, each set of options is organized in an inifile [section].
+
+=cut
+
+
 my %iniSetup;
 
 # Check for config and read
@@ -187,6 +249,21 @@ if (! -f $configFile) {
 	print STDERR "No configuration file found. Please answer the questions below to generate it.\n\n";
 
 	tie %iniSetup, 'Config::IniFiles';
+
+=head2 [server]
+
+LDAP server options.
+
+=head3 B<uri>=LDAP_URI
+
+Set the LDAP server URI, for example C<ldaps://example.com>.
+
+=head3 B<base>=BASE_DN
+
+Set the LDAP server base DN to use, for example C<dc=example,dc=com>.
+
+=cut
+
 	$iniSetup{server} = {};
 	$iniSetup{server}{uri} = prompt("Your LDAP URI     : ");
 	$iniSetup{server}{uri} =~ s/^uri=//;
@@ -212,6 +289,17 @@ if (!defined($ldapBase) || $ldapBase eq "") {
 	exit 1;
 }
 
+
+=head2 [pkcs11]
+
+Options for integration into PKCS11, this allows you to login to servers users a smartcard.
+
+=head3 B<provider>=PKCS11_PROVIDER
+
+Libary path of the PKCS11 provider. For example I</usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so>.
+
+=cut
+
 my $pkcsProvider = $config->val("pkcs11","provider");
 if (defined($pkcsProvider) && $pkcsProvider ne "") {
 	if (! -f $pkcsProvider) {
@@ -891,4 +979,29 @@ EOF
 }
 
 
+__END__
+
+=head1 AUTHORS
+
+Nigel Kukard E<lt>nkukard@allworld.itE<gt>, Robert Spencer E<lt>rspencer@allworld.itE<gt>
+
+=head1 BUGS
+
+All bugs should be reported via the project issue tracker
+L<https://gitlab.devlabs.linuxassist.net/allworldit/awit-ssh-client/issues>.
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright (C) 2016-2017, AllWorldIT
+
+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.
+
+=head1 SEE ALSO
+
+L<ssh>(1), L<rsync>(1), L<ssvncviewer>(1).
+
+=cut