Comment utiliser le module WinSCP de PowerShell ?

I. Présentation

WinSCP est un logiciel très pratique pour se connecter sur un serveur distant par l'intermédiaire de plusieurs protocoles : SFTP, SCP, FTP et WebDAV ou sur une instance Amazon S3. Il intègre une bibliothèque avec des fonctions .NET Framework qui permettent de l'utiliser en PowerShell. Ainsi, on peut interagir avec un serveur distant par l'intermédiaire de WinSCP directement dans un script PowerShell. La syntaxe des fonctions n'est pas très user-friendly, mais la bonne nouvelle c'est qu'il existe un module PowerShell "WinSCP" qui va nous simplifier la vie !

Dans ce tutoriel, je vais vous expliquer comment utiliser ce module WinSCP pour vous permettre de l'exploiter par vous-même dans vos scripts PowerShell. Le module est disponible sur GitHub et la PowerShell Gallery, voici les liens :

• WinSCP - Github
• WinSCP - PowerShell Gallery

II. Installer le module WinSCP de PowerShell

Pour installer ce module, c'est classique, il faut s'appuyer sur Install-Module comme ceci :

Install-Module -Name WinSCP

Si l'on regarde le contenu du module WinSCP, on remarque qu'il y a un dossier "bin" qui contient directement l'exécutable de WinSCP. Du coup, vous n'avez pas besoin d'installer WinSCP sur votre machine pour exploiter ce module, car il est intégré.

Si vous cherchez où s'est installé le module sur votre machine, utilisez cette commande :

Get-Module winscp | ft Path

Maintenant, nous allons voir comment utiliser ce module WinSCP. Je vais vous montrer quelques exemples d'utilisation et surtout la logique pour l'utiliser. Nous ne verrons pas toutes les commandes : il y en a une vingtaine...

II. Créer une connexion WinSCP avec PowerShell

Ce module permet d'envoyer des fichiers vers un hôte distant, mais également de télécharger des fichiers. Il permet aussi de renommer des fichiers, d'en supprimer, de lister le contenu, etc... Mais avant toute chose, il faut établir une connexion à l'hôte distant.

Pour créer une connexion, il faut tout d'abord définir des paramètres de session. En fait, nous allons utiliser trois commandes : New-WinSCPSessionOption, Get-WinSCPHostKeyFingerprint et New-WinSCPSession.

Intéressons-nous à la commande New-WinSCPSessionOption qui sert à définir les paramètres de la session. On va définir plusieurs paramètres :

• -Hostname : nom FQDN ou adresse IP de l'hôte distant
• -Protocol : protocole à utiliser (sftp, scp, webdav, ftp, s3)
• -PortNumber : port du serveur de destination
• -Credential : identifiants de connexion
• -SshHostKeyFingerprint : l'empreinte de la clé de l'hôte distant

Il y a d'autres paramètres, mais nous allons utiliser les 5 ci-dessus pour établir une connexion sur un serveur en SCP (ou SFTP). Ce qui donne, par exemple :

New-WinSCPSessionOption -HostName 192.168.5.150 -Protocol Sftp -PortNumber 22 -Credential (Get-Credential)

Nous devons stocker ces informations dans une variable :

$WinSCPSessionOption = New-WinSCPSessionOption -HostName 192.168.5.150 -Protocol Scp -PortNumber 22 -Credential (Get-Credential)

Ensuite, nous allons utiliser la commande Get-WinSCPHostKeyFingerprint pour récupérer l'empreinte de la clé SSH de l'hôte distant, car on ne peut pas la deviner... On va utiliser nos paramètres de session (paramètre -SessionOption) puis interroger l'hôte distant, puis la valeur sera stockée dans $sshHostKeyFingerprint.

$sshHostKeyFingerprint = Get-WinSCPHostKeyFingerprint -SessionOption $WinSCPSessionOption -Algorithm SHA-256

Ensuite, on va ajouter l'empreinte récupérée à nos paramètres de session :

$WinSCPSessionOption.SshHostKeyFingerprint = $sshHostKeyFingerprint

De manière générale, vous pouvez ajouter/modifier une valeur en suivant la syntaxe ci-dessus. Par exemple pour modifier le port :

$WinSCPSessionOption.PortNumber = 222

Maintenant, on peut monter la connexion vers l'hôte distant avec le cmdlet New-WinSCPSession et en utilisant nos paramètres de connexion (-SessionOption).

$WinSCPSession = New-WinSCPSession -SessionOption ($WinSCPSessionOption)

On peut s'assurer que la connexion est bien active en exécutant la commande suivante :

Get-WinSCPSession

III. Envoyer un fichier avec le module WinSCP de PowerShell

Nous allons voir comment envoyer un fichier vers l'hôte distant auquel on s'est connecté. Tout d'abord, on peut lister le contenu du répertoire courant avec Get-WinSCPChildItem. Sur le même principe que Get-ChildItem et Get-Item, il existe la commande Get-WinSCPItem.

Ce sera l'occasion de voir où l'on se situe sur le serveur distant :

Get-WinSCPChildItem -WinSCPSession $WinSCPSession -Path .

Le contenu sera listé ainsi que le dossier courant : de quoi se repérer. En fait, sur le principe à chaque fois que l'on exécute une commande il faut appeler notre session avec -WinSCPSession $WinSCPSession.

Pour envoyer un fichier à partir de notre connexion SCP, on va utiliser le cmdlet Send-WinSCPItem. En complément des options de session, on va utiliser deux paramètres : -Path, c'est-à-dire la source, et -Destination.

Note : en fonction du protocole utilisé, les paramètres ne sont pas les mêmes dans les commandes associées. Si vous recherchez une option spécifique, n'hésitez pas à consulter l'aide du module WinSCP. Par ailleurs, si le serveur distant réagit mal (renvoie une erreur) lorsque vous utilisez le protocole SCP, basculez simplement en SFTP pour voir si cela fonctionne.

Ce qui donne :

Send-WinSCPItem -WinSCPSession $WinSCPSession -Path "C:\temp\fichier.jpg" -Destination "/home/florian/"

Ensuite, si l'on veut vérifier que le fichier est bien arrivé à destination par une commande complémentaire, on va utiliser Get-WinSCPItem :

Get-WinSCPItem -WinSCPSession $WinSCPSession -Path /home/florian/fichier.jpg

On pourrait faire autrement puisqu'il y a un équivalent de Test-Path dans ce module : Test-WinSCPPath, il renvoie aussi un booléen. Ce qui donne :

Test-WinSCPPath -WinSCPSession $WinSCPSession -Path /home/florian/fichier.jpg

Voilà, nous venons d'envoyer un fichier avec succès sur l'hôte distant ! Pour finir, on pourrait avoir besoin de renommer le fichier envoyé, dans ce cas on va utiliser Rename-WinSCPItem. Nous avons besoin de deux paramètres spécifiques : -Path qui correspond au chemin complet vers le fichier et -NewName qui correspond au nouveau nom à associer au fichier.

Pour renommer le fichier "/home/florian/fichier.jpg" en "it-connect.jpg" :

Rename-WinSCPItem -WinSCPSession $WinSCPSession -Path "/home/florian/fichier.jpg" -NewName "it-connect.jpg"

Passons à la suite...

IV. Télécharger un fichier avec le module WinSCP de PowerShell

Nous avons vu comment envoyer un fichier, voyons comment télécharger un fichier du serveur distant vers notre machine locale. Pour cela, on va utiliser Receive-WinSCPItem avec deux options : -RemotePath, c'est-à-dire le chemin complet vers le fichier distant, puis -LocalPath c'est-à-dire le dossier local dans lequel déposer le fichier téléchargé.

Receive-WinSCPItem -WinSCPSession $WinSCPSession -RemotePath /home/florian/fichier.jpg -LocalPath "C:\"

Si l'on ajoute le paramètre -Remove, il sera supprimé automatiquement du répertoire distant.

Receive-WinSCPItem -WinSCPSession $WinSCPSession -RemotePath /home/florian/fichier.jpg -LocalPath "C:\" -Remove

Il faut savoir que ce paramètre -Remove fonctionne aussi avec la commande Send-WinSCPItem.

V. Supprimer un fichier avec le module WinSCP de PowerShell

La suppression d'un fichier passe par l'utilisation de Remove-WinSCPItem, on va lui spécifier simplement le chemin vers le fichier à supprimer avec -Path. En complément, on positionnera le paramètre -Confirm sur $false pour supprimer la demande de confirmation.

Remove-WinSCPItem -WinSCPSession $WinSCPSession -Path "/home/florian/fichier.jpg" -Confirm:$false

VI. Fermer la session WinSCP

Pour finir et faire les choses proprement, on va fermer la session WinSCP à la fin :

Remove-WinSCPSession

A vous de jouer maintenant !

Florian BURNEL Co-founder of IT-Connect

Ingénieur système et réseau, cofondateur d'IT-Connect et Microsoft MVP "Cloud and Datacenter Management". Je souhaite partager mon expérience et mes découvertes au travers de mes articles. Généraliste avec une attirance particulière pour les solutions Microsoft et le scripting. Bonne lecture.

Voir la bio complète