Skip to content

Commit 0c99729

Browse files
v-tappelgatev-tappelgate
committed
AB7807: Troubleshoot SFTP issues when using OpenSSH
New article for [CI 7807](https://dev.azure.com/KMOps/ContentExperience/_queries/edit/7807)
1 parent c9fdfb4 commit 0c99729

1 file changed

Lines changed: 135 additions & 0 deletions

File tree

‎support/windows-server/system-management-components/troubleshoot-sftp-issues-using-openssh.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
2+
---
3+
title: How to Enable OpenSSH Verbose Logging
4+
description: Explains how to resolve common SFTP issues when using OpenSSH for Windows.
5+
ms.date: 11/05/2025
6+
manager: dcscontentpm
7+
audience: itpro
8+
ms.topic: troubleshooting
9+
ms.reviewer: kaushika, warrenw, v-appelgatet
10+
ms.custom:
11+
- sap:system management components\openssh (including sftp)
12+
- pcy:WinComm User Experience
13+
appliesto:
14+
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Supported versions of Windows Server</a>
15+
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Supported versions of Windows Client</a>
16+
---
17+
# Troubleshoot SFTP issues
18+
19+
OpenSSH on Windows provides secure file transfer (SFTP) capabilities. This article describes how to resolve the most common issues that you might encounter while using SFTP and OpenSSH to administer Windows Server and Windows Client.
20+
21+
## Best Practices and Additional Resources
22+
23+
- Use the latest supported OpenSSH version.
24+
- Avoid configuring OpenSSH to use a network share for the chroot directory.
25+
- Every time that you change the OpenSSH Server configuration, validate the change by running `sshd -t`.
26+
- When you start troubleshooting, check Event Viewer for relevant events.
27+
28+
For more information about configuring OpenSSH on Windows and Windows Server, see the following articles:
29+
30+
- [Get started with OpenSSH for Windows](/windows-server/administration/openssh/openssh_install_firstuse)
31+
- [OpenSSH Server configuration for Windows Server and Windows](/windows-server/administration/openssh/openssh-server-configuration)
32+
33+
### How to enable SFTP logging
34+
35+
To enable SFTP logging for the OpenSSH Server service, modify the sshd_config file, and restart the OpenSSH Server service. Follow these steps:
36+
37+
1. Use an administrator-level account to open a text editor, and then open **%ProgramData%\ssh\sshd_config**. The default text of the "Logging" section should resemble the following excerpt:
38+
39+
```output
40+
# Logging
41+
#SyslogFacility AUTH
42+
#LogLevel INFO
43+
```
44+
45+
1. To enable SFTP logging, edit the text to resemble the following excerpt:
46+
47+
```output
48+
# Logging
49+
SyslogFacility LOCAL0
50+
LogLevel DEBUG3
51+
```
52+
53+
Also, add (or modify) the following text:
54+
55+
```output
56+
Subsystem sftp sftp-server.exe -f LOCAL0 -l DEBUG3
57+
```
58+
59+
1. Save and close the sshd_config file.
60+
61+
1. To restart the OpenSSH Server service, open a Windows Command Prompt window, and then run the following command:
62+
63+
```console
64+
NET STOP "OpenSSH SSH Server" && NET START "OpenSSH SSH Server"
65+
```
66+
67+
After the service restarts, it generates SFTP log data in %ProgramData%\ssh\logs. For more information about OpenSSH logging, see [How to enable OpenSSH verbose logging](enable-openssh-verbose-logging.md).
68+
69+
## Common SFTP Issues on Windows and Windows Server
70+
71+
### SFTP users land in the wrong directory or outside the chroot jail
72+
73+
When correctly configured, the chroot directory restricts (jails) users to a specific directory tree. This restriction prevents users from accessing the rest of the file system.
74+
75+
Check the following settings:
76+
77+
- In the sshd_config file, make sure that `ChrootDirectory` points to a local directory and doesn't use a UNC path.
78+
- Make sure that SYSTEM/Administrators has owner permissions on the chroot directory.
79+
- Make sure that each user has a writeable directory within the chroot directory, and make sure that the directory has the correct permissions. Secure the /.ssh/authorized_keys files.
80+
81+
> [!NOTE]
82+
> To verify and fix NTFS permissions, use [icacls](/windows-server/administration/windows-commands/icacls) command at an administrative Command Prompt window.
83+
84+
- In the sshd_config file, use`ForceCommand internal-sftp`, and use the -d switch with the `Subsystem sftp sftp-server.exe` command to set an upload directory. You can use these settings in `Match` blocks to specify users.
85+
86+
### Particular users can't use SFTP or receive "Access denied" errors
87+
88+
This behavior indicates ownership or permissions issues. Check the following settings:
89+
90+
- Make sure that SYSTEM/Administrators has owner permissions on the chroot directory.
91+
- Make sure that each user has a writeable directory within the chroot directory, and make sure that the directory has the correct permissions. Secure the /.ssh/authorized_keys files.
92+
93+
> [!NOTE]
94+
> To verify and fix NTFS permissions, use [icacls](/windows-server/administration/windows-commands/icacls) command at an administrative Command Prompt window.
95+
96+
### Users can't sign in or receive "Authentication failed", or "Server refused our key" errors
97+
98+
This behavior indicates public key or password issues. Check the following configurations:
99+
100+
- Use C:\ProgramData\ssh\administrators_authorized_keys to store keys, and use `icacles` to check the file and folder permissions.
101+
- If the server refused the key, add the following lines to sshd_config:
102+
103+
```console
104+
PubkeyAcceptedKeyTypes +ssh-rsa
105+
HostKeyAlgorithms +ssh-rsa
106+
```
107+
108+
> [!NOTE]
109+
> After you make these changes, restart the OpenSSH Server service.
110+
111+
### OpenSSH Server service doesn't start, or SFTP connections hang
112+
113+
SFTP server fails to start after configuration changes or Windows Updates - A. Service and Connection Failures - Scenario 3: SFTP Connections Hang - Scenario 4: SFTP Fails After Windows Update - SFTP connections hang or timeout
114+
115+
To resolve these issues, try the following actions:
116+
117+
- To validate the sshd_config settings, run the `sshd -t` command.
118+
- Review Event Viewer for any relevant events.
119+
- To check and repair ACLs on the chroot directory tree, run the `icacles` command.
120+
- Review the sshd_config settings. Make sure that the entries don't have any trailing spaces, and make sure that the `Subsystem sftp sftp-server.exe` command is present.
121+
122+
If none of these actions resolve the issue, uninstall OpenSSH Server and then reinstall it.
123+
124+
### SFTP logs are missing or incomplete
125+
126+
Review the log settings in ssdh_config. As described in [How to enable SFTP logging](#how-to-enable-sftp-logging), SFTP log data is stored in %ProgramData%\ssh\logs.
127+
128+
To check and repair ACLs on the log folder, run the `icacles` command.
129+
130+
### Users can't upload or download files
131+
132+
- In the sshd_config file, make sure that `ChrootDirectory` points to a local directory and doesn't use a UNC path.
133+
- Make sure that SYSTEM/Administrators has owner permissions on the chroot directory.
134+
- Make sure that each user has a writeable directory within the chroot directory, and make sure that the directory has the correct permissions. To check and repair ACLs, run the `icacles` command.
135+
- Make sure that users don't have writer permission on the chroot directory.

0 commit comments

Comments
 (0)