doc #1753 sftp: prefer ~/.ssh/config over ssh_keyfile in credentials.conf - #1757
robjarawan wants to merge 1 commit into
Conversation
…ials.conf Ordinary sftp transfers go through paramiko, which sarracenia configures from credentials.conf. Transfers over accelThreshold are handed to scp, which reads ~/.ssh/config and cannot see credentials.conf. A key given as ssh_keyfile is therefore used by ordinary transfers and silently missing from accelerated ones, so a working config starts failing once a file crosses the threshold. Settings in ~/.ssh/config are read by both paths, scp natively and paramiko via the lookup in Sftp.credentials(), so document a Host stanza with no credentials.conf entry as the way to configure sftp. Also documents that a port belongs in the stanza rather than the URL, since a port in the URL is not passed to scp correctly, and notes that ~/.ssh/config is only consulted when the credential does not already supply a user and a secret.
|
The changes are good. Just need french changes as well. |
| Sarracenia only consults ``~/.ssh/config`` when the credential does not already answer | ||
| the question: when no user is known, or when neither a key nor a password was supplied. | ||
| A ``credentials.conf`` entry carrying a user and a password takes precedence and the | ||
| stanza is not read. Omitting the entry is the reliable way to have ``~/.ssh/config`` | ||
| apply. |
There was a problem hiding this comment.
I'm not 100% sure how this works, I think .ssh/config is always used, I don't know which overrides which (does credentials.conf override .ssh/config or is it the other way around?)
|
I verified every claim in this doc change against First, the subscriber stanza problem is real and the doc needs a warning. Second, the precedence note must read user plus a secret. Per Third, French translation stays a follow-up. The port-mangling wording is accurate for both get and put paths. |
What
Closes #1753 as documentation, per the discussion there.
ssh_keyfileincredentials.confis used by ordinary sftp transfers and silently ignoredby accelerated ones. Transfers over
accelThresholdare handed toscp, which reads~/.ssh/configand cannot seecredentials.conf. The symptom is a configuration that worksuntil a file crosses the threshold, so it presents as "large files fail" rather than as a
credential problem.
Settings in
~/.ssh/configare read by both paths:scpnatively, and paramiko becauseSftp.credentials()looks the host up in~/.ssh/configitself and takesHostName,User,PortandIdentityFilefrom it.Change
Adds a
SFTP and ~/.ssh/configsection tosr3_credentials.7.rstdocumenting aHoststanza with no
credentials.confentry as the way to configure sftp, and points to it fromthe
ssh_keyfileentry under Credential Details.It also records two things that are easy to lose an afternoon to:
scpcorrectly, so an accelerated transfer to
sftp://user@host:2222/fails while an ordinarytransfer to the same URL succeeds.
~/.ssh/configis only consulted when the credential does not already answer the question(
transfer/sftp.py:285-286). An entry carrying a user and a password takes precedence andthe stanza is not read, so omitting the entry is the reliable way to have it apply.
Documentation only. No code changes.
Verified
Every statement in the new section was run against a real sftp server on unmodified
development, not reasoned about. Lab account whoseauthorized_keysholds only adeliberately odd named key, so nothing succeeds by accident, plus a second sshd on 2222 for
the port case. 2 MB file,
accelThreshold 1M, md5 compared against the source on thesuccessful runs.
ssh_keyfilein credentials.confPermission denied (publickey)Port 2222, alias in URL2222:/path: No such fileRST checked with docutils. The only diagnostics are the pre-existing
|today|and|release|substitutions that sphinx supplies at build time.Not included
The French
docs/source/fr/Reference/sr3_credentials.7.rstcarries the matchingssh_keyfileentry and is not updated here. I would rather that was done by someone whowrites French properly than guessed at, but I can attempt it if you would prefer it in the
same change.
Two unrelated defects turned up while testing this and are filed separately, both with
reproductions and no patch: #1755 (accelerated sftp fails when baseUrl contains a path) and
#1756 (accelerated transfers break on filenames containing spaces, across all five
accelerated call sites).
Fork CI
Run on my fork first: robjarawan#136 - 32 pass, 6 fail.
The six failures are runner flakiness, not this change. The clearest evidence is that the
duplicate workflow runs on the same commit disagree with themselves:
Every job that failed also passed on another run of the same commit. The same jobs are
also currently failing on untouched
developmentupstream.This branch changes one .rst file and a changelog line, with no python or config touched,
so the flow tests cannot be reached by it.
A passing dynamic_flow run: https://github.com/robjarawan/sarracenia/actions/runs/30972432267/job/92199482505