.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SSH::AuthorizedKeysFile 3pm"
.TH Net::SSH::AuthorizedKeysFile 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SSH::AuthorizedKeysFile \- Read and modify ssh's authorized_keys files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::SSH::AuthorizedKeysFile;
\&
\&        # Reads $HOME/.ssh/authorized_keys by default
\&    my $akf = Net::SSH::AuthorizedKeysFile\->new();
\&
\&    $akf\->read("authorized_keys");
\&
\&        # Iterate over entries
\&    for my $key ($akf\->keys()) {
\&        print $key\->as_string(), "\en";
\&    }
\&
\&        # Modify entries:
\&    for my $key ($akf\->keys()) {
\&        $key\->option("from", \*(Aqquack@quack.com\*(Aq);
\&        $key\->keylen(1025);
\&    }
\&        # Save changes back to $HOME/.ssh/authorized_keys
\&    $akf\->save() or die "Cannot save";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::SSH::AuthorizedKeysFile reads and modifies \f(CW\*(C`authorized_keys\*(C'\fR files.
\&\f(CW\*(C`authorized_keys\*(C'\fR files contain public keys and meta information to
be used by \f(CW\*(C`ssh\*(C'\fR on the remote host to let users in without 
having to type their password.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP """new""" 4
.el .IP "\f(CWnew\fR" 4
.IX Item "new"
Creates a new Net::SSH::AuthorizedKeysFile object and reads in the 
authorized_keys file. The filename 
defaults to \f(CW\*(C`$HOME/.ssh/authorized_keys\*(C'\fR unless
overridden with
.Sp
.Vb 1
\&    Net::SSH::AuthorizedKeysFile\->new( file => "/path/other_authkeys_file" );
.Ve
.Sp
Normally, the \f(CW\*(C`read\*(C'\fR method described below will just silently ignore 
faulty lines and only gobble up keys that either one of the two parsers
accepts. If you want it to be stricter, set
.Sp
.Vb 2
\&    Net::SSH::AuthorizedKeysFile\->new( file   => "authkeys_file",
\&                                       abort_on_error => 1 );
.Ve
.Sp
and read will immediately abort after the first faulty line. Also, 
the key parsers are fairly lenient in default mode. Adding
.Sp
.Vb 1
\&    strict => 1
.Ve
.Sp
adds sanity checks before a key is accepted.
.ie n .IP """read""" 4
.el .IP "\f(CWread\fR" 4
.IX Item "read"
Reads in the file defined by \fBnew()\fR. By default, strict mode is off and 
\&\fBread()\fR will silently ignore faulty lines. If it's on (see \fBnew()\fR above),
\&\fBread()\fR will immediately abort after the first faulty line. A textual
description of the last error will be available via \fBerror()\fR.
.ie n .IP """content""" 4
.el .IP "\f(CWcontent\fR" 4
.IX Item "content"
Contains the original file content, read by \f(CW\*(C`read()\*(C'\fR earlier. Can be
used to set arbitrary content:
.Sp
.Vb 1
\&    $keysfile\->content( "some\enrandom\enlines\en" );
.Ve
.Sp
and have \f(CW\*(C`parse()\*(C'\fR operate on a string instead of an actual file 
this way.
.ie n .IP """keys""" 4
.el .IP "\f(CWkeys\fR" 4
.IX Item "keys"
Returns a list of Net::SSH::AuthorizedKey objects. Methods are described in
Net::SSH::AuthorizedKey.
.ie n .IP """as_string""" 4
.el .IP "\f(CWas_string\fR" 4
.IX Item "as_string"
String representation of all keys, ultimately the content that gets
written out when calling the \f(CW\*(C`save()\*(C'\fR method. 
Note that comments from the original file are lost.
.ie n .IP """save""" 4
.el .IP "\f(CWsave\fR" 4
.IX Item "save"
Write changes back to the authorized_keys file using the \fBas_string()\fR
method described above. Note that comments from the original file are lost.
Optionally takes a file
name parameter, so calling \f(CW\*(C`$akf\->save("foo.txt")\*(C'\fR will save the data
in the file \*(L"foo.txt\*(R" instead of the file the data was read from originally.
Returns 1 if successful, and undef on error. In case of an error, \fBerror()\fR
contains a textual error description.
.ie n .IP """sanity_check""" 4
.el .IP "\f(CWsanity_check\fR" 4
.IX Item "sanity_check"
Run a sanity check on the currently selected authorized_keys file. If
it contains insanely long lines, then parsing with \fBread()\fR (and potential
crashes because of out-of-memory errors) should be avoided.
.ie n .IP """ssh_dir( [$user] )""" 4
.el .IP "\f(CWssh_dir( [$user] )\fR" 4
.IX Item "ssh_dir( [$user] )"
Locate the .ssh dir of a given user. If no user name is given, ssh_dir will
look up the .ssh dir of the effective user. Typically returns something like
\&\*(L"/home/gonzo/.ssh\*(R".
.ie n .IP """path_locate( [$user] )""" 4
.el .IP "\f(CWpath_locate( [$user] )\fR" 4
.IX Item "path_locate( [$user] )"
Locate the authorized_keys file of a given user. Typically returns something 
like \*(L"/home/gonzo/.ssh/authorized_keys\*(R". See \f(CW\*(C`ssh_dir()\*(C'\fR for how the 
containing directory is located with and without a given user name.
.ie n .IP """error""" 4
.el .IP "\f(CWerror\fR" 4
.IX Item "error"
Description of last error that occurred.
.SH "LEGALESE"
.IX Header "LEGALESE"
Copyright 2005\-2009 by Mike Schilli, all rights reserved.
This program is free software, you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
2005, Mike Schilli <m@perlmeister.com>