Moduł Net::SFTP

Uniwersytet Gdański - Instytut Matematyki - Zakład Informatyki - Strona domowa

Spis treści

  1. Co to jest?
  2. Metody
  3. Metody-komendy
  4. Dodatkowe informacje

Co to jest?

Net::SFTP jest sciśle perlowa implementacja protokołu SFTP (Secure File Transfer Protocol) - transfer plików zbudowany na protokole SSH2. Net::SFTP używa Net::SSH::Perl aby zbudować bezpieczny, szyfrowany tunel przez który pliki mogą być przesyłane oraz zarządzane. Zapewnia podzbiór komend spisanych w projekcie SSH FTP IETF.

SFTP jest to skrót od Secure File Transfer Protocol (Bezpieczny Protokół Transferu Plików) jest to metoda przesyłania plików pomiędzy dwoma maszynami poprzez bezpieczne, szyfrowane połączenie (w przeciwieństwie do standardowego FTP, który oparty jest na niezabezpieconym połączeniu). Bezpieczoństwo SFTP pochodzi z jego połączenia z SSH, które zapewnia szyfrowaną warstwe transfortową na której wykonywane sa polecenia SFTP, oraz dzieki której pliki mogą być przesyłane. Protokół SFTP definiuje klienta oraz server; tylko klient, serwer natomias nie jest zaimplementowany w Net::SFTP

Dzieki zbudowaniu na SSH, SFTP dziedziczy wszystkie wbudowane funkcjonalności dostarczone przez Net::SSH::Perl: szyfrowanie, komnikacje pomiedzy klientem i serwerem, wielokrotne poświadczenie (np. hasło, klucz publiczny, itp.)

Metody

Net::SFTP->new($host, %args)

Otwiera nowe połączenie SFTP ze zdalnym hostem $host, zwraca Net::SFTP obiekt reprezentujący połączenie

%args może zawierać:

  • user

    • Nazwa użytkownika jaka ma zostać użyta do logowania na zdalnym serwerze. Powinien to byc twój login SSH, może byc pusty, w takim przypadku zostanie użyta nazwa użytkownika który uruchomił proces.

    Aby zapoznać się ze szczegółami zobacz metode login w Net::SSH::Perl

  • password

    • Hasło które zostanie użyte do logowania sie na zdalnym serwerze. Powinno to być hasło używane do połączeń SSH, jeśli używasz hasła w łączeniu SSH; jeśli używasz kluczy publicznych w poświadczeniu, ten agrument jest użyty.

    Zobacz metode login z Net::SSH::Perl aby poznać więcej szczegółów.

  • debug

    • Jeśli ustawione na prawda, wiadomosci debugowania bedea wyswietlane z obu protokołów SSH jak i SFTP. Włącza automatycznie parametr debug w Net::SSH::Perl. Domyślnie ustawine na fałsz

  • warn

    • Jeśli dana jest referencja do funkcji, funkcja jest wywołana z $self oraz każde ostrzeżenia; jesli ustawione na fałsz, ostrzeżenia sa wyłaczane; w innym przypadku sa wypisywane z 'warn'(domyślnie).

  • ssh_args

    • Wyszczególnia referencje do lisy albo hasza nazwanych argumentów powinien być dany do konstruktora Net::SSH::Perl obiekt leżacy pod połączeniem Net::SFTP.

    Na przykład, możemy tego użyc do założnia plików tożsamoscowych, do wybrania odpowiedniego szyfrowania itd.

$sftp->status

Zwraca ostatną zdalną wartość statusu SFTP. Użyteczne jedynie jeśli jedna z kolejnych metod zawiedzie. Zwraca SSH2_FX_OK jeśli nie ma zadnego zdalnego błędu (np. plik lokalny nie znaleziony). W kontekście listowym, zwraca liste składającą sie z (kodu statusu, statusu textowego z fx2txt).

Jeśli wystąpił błąd nisko poziomowego protokółu bądz nieoczekiwany lokalny błąd, kończymy z wiadomościa o błędzie.

$sftp->get($remote [, $local [, \&callback ] ])

Pobiera plik $remote ze zdalnego hosta. Jeśli $local jest wskazana, jest otwarta/stworzona, zawartość pliku $remote zapisana zostaje do $local. W dodatku, jego atrybuty (czas dostepu,prawa,itp.) bedą ustawione takie same jak pliku zdalnego.

Jeśli get jest wywołana z nie pustego kontekstu, zwraca zawartośc $remote (jak również zapisuje je do $local, jeśli $local jest dostarczone). W przypadku błędu zwracane jest undef.

$local jest opcjonalne. Jeśli nie jest dostarczone, zawartość zdalnego pliku $remote zostanie albo porzucona, jeśli get zostało wywołane w pustym kontekscie, albo zwrucone przez $get jeśli zostało wywołane w niepustym kontekście.

$sftp->put($local, $remote [, \&callback ])

Wysyła plik $local z lokalnego hosta do zdalnego hosta, i zapisuje go jako $remote.

Jeśli \&callback jest określony, powinno być referencją do funkcji. Funkcja zostanie wykonana za każdą iteracja pętli write, odrazu po przeczytaniu danych z pliku lokalnego. Funkcja callback (powrotna) otrzyma jako argument: obiekt typu Net::SFTP z otwartym połączeniem SFTP; dane przeczytane z $local, ogólnie w częsciach 8192 bjtowych; o offsecie z początku pliku (w bajtach); i całkowitym rozmiarze pliku (w bajtach). Można użyc mechanizu do dostarczenia statusu wiadomości, mierzenia prostępu wysylania, np.:

sub callback { my($sftp, $data, $offset, $size) = @_; print "Wrote $offset / $size bytes\r"; }

Zwraca prawde jeśli sie udało, undef jeśli wystąpił błąd

$sftp->ls($remote [, $subref ])

Przynosi dokładny spis $remote.

Jeśli $subref jest określone, dla każdej pozycji w folderze, $subref bedzie wywołane i dane referencje do hasha z drzewem kluczy: nazwa pliku, nazwa pozycji w spisie folderu; dluga nazwa, pozycja w "długiej" liście tak jak ls -l; oraz obiekt Net::SFTP::Attributes, który zawiera atrybuty pliku (czas dostepu, prawa, itp.)

Jeśli $subref nie jest określone, zwraca listę wpisów folderów, każda z nich jest referencją do hasha tak jak opisane w poprzednim paragrafie.

Metody-komendy

Net::SFTP obsługuje wszystkie komendy spisane w specyfikacji protokołu SFTP wersja 3. Każda komenda jest dostepna do wykonania jako oddzielna metoda, z kilkoma wyjątkami:SSH_FXP_INIT, SSH_FXP_VERSION, oraz SSH_FXP_READDIR.

To są komendy dostępne poprzez metody:

$sftp->do_open($path, $flags [, $attrs ])

Wysyła komendę SSH_FXP_OPEN aby otworzyć zdalny plik $path, zwraca otwarty uchwyt jeśli wszystko sie uda. Jeśli nie zwraca undef. Otwarty uchwyt nie jest Prelowym uchwytem do pliku, ani deskryptorem; jest jedynie znacznikiem aby zidentyfikować plik pomiędzy klientem a serwerem.

$flags powinna byc maską bitową otwartych flag, te wartości mogą być uzyskane z from Net::SFTP::Constants:

use Net::SFTP::Constants qw( :flags );

$attrs piwinny byc obiektem Net::SFTP::Attributes wyszczególniajacym początkowe atrybuty dla każdego pliku $path. Jeśli otwierasz plik jedynie do odczytu, $attrs mogą pozostac puste, w tym przypadku zostaną zainicjowane jako puste zbiór atrybutów.

$sftp->do_read($handle, $offset, $copy_size)

Wysyła komende SSH_FXP_READ do czytania z otwartego uchwytu do pliku $handle, zaczynając od $offset, i czyta co najwyżej $copy_size bajtów.

Zwraca dwu elementową liste składającą się z danych przeczytanych z servera SFTP w pierszej częsci, oraz kodu statusu (jeśli jest jakikolwiek) w drugiej. W przypadku pomyślnego czytania, kod statusu bedzie undef, a dane beda określone jako prawdziwe. W przypadku napotkania EOF, wartośc statusu bedzie SSH2_FX_EOF, a dane undef. W przypadku błędu w czytaniu, ostrzeżenie bedie wyświetlone, status bedzie zawierał kod błędu, a data bedzie undef.

$sftp->do_write($handle, $offset, $data)

Wysyła komende SSH_FXP_WRITE aby otworzyc uchwyt do pliku $handle, zaczynając od $offset, dane natomiast maja zostać zapisane w $data.

Zwraca kod statusu. Jeśli udało sie zapisać, status bedzie równy SSH2_FX_OK w przypadku nieudanego zapisu, ostrzeżenie zostanie wyświetlone, a kod statusu bedzie zawierał błąd zwrucony przez serwer.

$sftp->do_close($handle)

Wysyła komende SSH_FXP_CLOSE aby zamknąc albo otwarty plik, albo folder, identyfikowany poprzez $handle

Wypisuje ostrzeżenie jeśli zamykanie nie uda sie.

Zwraca status po operacji. Aby zamienić status da wiadomość tekstową, spójż na funkcje fx2txt w Net::SFTP::Util.

$sftp->do_lstat($path)
$sftp->do_stat($path)
$sftp->do_fstat($handle)

Wszystkie te trzy metody mają podobną funkcjonalność: uruchamiaja stat na zdalnym pliku oraz zwracaja rezultat w obiekcie Net::SFTP::Attributes jeśli sie powiedzie.

W razie niepowodzenia wszystkie trzy zwarcaja undef, oraz wypisuja ostrzeżenie.

$sftp->do_setstat($path, $attrs)
$sftp->do_fsetstat($handle, $attrs)

Te dwie metody działają podobnie: ustawiaja atrybuty zdalnego pliku. W obu przypadkach $attrs powinien być obiektem Net::SFTP::Attributes.

do_setstat wysyła komende SSH_FXP_SETSTAT aby ustawić atrybuty dla pliku$path na $attrs.

do_fsetstat wysyła komende SSH_FXP_FSETSTAT aby ustawić atrybuty dla otwartego uchwytu do pliku $handle na $attrs.

Obie metody wypisuja ostrzeżenie jeśli operacja się nie powiedzie, oraz obie zwracają status operaci.

$sftp->do_opendir($path)

Wysyła komende SSH_FXP_OPENDIR aby otowrzyc zdalny folder $path, zwraca uchwyt jeśli operacja zakończyła sie sukcesem. Jeśli niepowodzenie zwraca undef.

$sftp->do_remove($path)

Wysyła komende SSH_FXP_REMOVE aby usunąc zdalny plik $path.

Wypisuje ostrzeżenie jeśli operacja się nie uda.

$sftp->do_mkdir($path, $attrs)

Wysyła komende SSH_FXP_MKDIR aby stworzyć zdalny folder $path którego atrybuty powinny być zainicjowane do $atts, obiektu Net::SFTP::Attributes.

Wypisuje ostrzeżenie jeśli operacja się nie uda.

$sftp->do_rmdir($path)

Wysyła komende SSH_FXP_RMDIR aby usunąc zdalny folder $path.

Wypisuje ostrzeżenie jeśli operacja się nie uda.

$sftp->do_realpath($path)

Wysyła komende aby przetworzyć $path do ścieżki absolutnej. Może byc to pomocne aby zamienic ścieżki zawierające '..' do ścieżki absolutnej.

Zwraca absoujną ścieżke jeśli operacja się powiedzie, undef jeśli nie.

$sftp->do_rename($old, $new)

Wysyła komende SSH_FXP_RENAME aby zmienić nazwę $old na $new.

Wypisuje ostrzeżenie jeśli operacja się nie uda.

Dodatkowe informacje.

Dlaczego wybrałem ten moduł?

Do programów perlowych potrzebowałem plików pobieranych w trakcie działania programu ze zdalnego serwera. Do tego celu używałem innego modułu perlowego Net::SCP jednak po pewnym czasie jego używania zdałem sobie sprawę z jego ograniczeń. Moduł Net::SFTP nie ma takich ograniczeń nie ma, nie potrzebuje żadnych zewnętrznych progamów. Więc jest przenośny i ma dużą funkcjonalność.

Mój przykładowy program
use Net::SFTP; $proc = sub { my %hasz=%{$_[0]}; if(substr($hasz{filename},0,1) eq "." && substr($hasz{longname},0,1) ne "d"){ $sftp->get("./".$hasz{filename},$hasz{filename}); } }; if($#ARGV < 2){exit 0;} $folder = time; %args=(user,$ARGV[0],password,$ARGV[1],debug,1); $sftp = Net::SFTP->new($ARGV[2],%args); `mkdir $folder`; chdir "./".$folder; $sftp->ls("./",$proc); chdir "../"; `tar -cvzf ukryte.tar.gz $folder`; `rm -rf $folder`;

Program pobiera wszystkie ukryte pliki z folderu po połączeniu i zapisuje je jako archiwum tar.gz

Przydatne linki

Dokumentacja tego modułu w cpan'ie
To samo trochę dokładniej
Błędy można zgłaszać tu

Kontakt i informacje o autorze opracowania

Autorzy modułu:

projektem obecnie zajmuje sie David Robins, dbrobins@cpan.org.

Wcześniej projekt podtrzymywał Dave Rolsky, autarch@urth.org.

Pierwotnie napisane przez Benjamina Trotta.

Autor prekładu: MD

Numer GG: Słoneczko 2194164

Uniwersytet Gdański - Instytut Informatyki - Strona domowa - Perl - Wyklady
[c] Piotr Arłukowicz, materiały z tej strony udostępnione są na licencji GNU.