build based on 4a4f2e4

dev/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-10-10T16:18:12","documenter_version":"1.7.0"}}
+{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-10-11T15:21:48","documenter_version":"1.7.0"}}

dev/contributing/index.html

@@ -6,4 +6,4 @@
 # infinite loop.
 julia&gt; servedocs(; include_dirs=[&quot;src&quot;], skip_files=[&quot;docs/src/examples.md&quot;, &quot;docs/src/generated_changelog.md&quot;])</code></pre><p>This will start a server with <a href="https://github.com/tlienart/LiveServer.jl">LiveServer.jl</a> to automatically rebuild the docs when they&#39;re changed. But if you&#39;ve done something like changed a docstring and only want to build it once, this will work too:</p><pre><code class="language-julia hljs">pkg&gt; activate docs
 julia&gt; include(&quot;docs/make.jl&quot;)</code></pre><p>Note that the examples are generated automatically from <code>docs/src/examples.jl</code>.</p><h3 id="Updating-the-bindings"><a class="docs-heading-anchor" href="#Updating-the-bindings">Updating the bindings</a><a id="Updating-the-bindings-1"></a><a class="docs-heading-anchor-permalink" href="#Updating-the-bindings" title="Permalink"></a></h3><p>If there&#39;s a new upstream release of libssh, here&#39;s how to update everything:</p><ol><li><p>Update the <a href="https://github.com/JuliaPackaging/Yggdrasil/blob/master/L/libssh/build_tarballs.jl"><code>build_tarballs.jl</code></a> script to build the new version, and submit a PR to Yggdrasil to update <code>libssh_jll</code>. When testing it&#39;s often useful to deploy it locally first:</p><pre><code class="language-bash hljs">$ julia --project=@project-with-binary-builder build_tarballs.jl --deploy=local</code></pre></li><li><p>Update the generated bindings:</p><pre><code class="language-julia-repl hljs">pkg&gt; activate gen
-julia&gt; include(&quot;gen/gen.jl&quot;)</code></pre><p>If you&#39;ve build and deployed <code>libssh_jll</code> locally make sure to <code>pkg&gt; dev libssh_jll</code> first, or <code>] up</code> if the JLL has already been updated in Yggdrasil.</p></li><li><p>Run the tests to make sure everything works, then bump the LibSSH.jl version number and release \o/</p></li></ol></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../generated_changelog/">« Changelog</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Thursday 10 October 2024 16:18">Thursday 10 October 2024</span>. Using Julia version 1.11.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+julia&gt; include(&quot;gen/gen.jl&quot;)</code></pre><p>If you&#39;ve build and deployed <code>libssh_jll</code> locally make sure to <code>pkg&gt; dev libssh_jll</code> first, or <code>] up</code> if the JLL has already been updated in Yggdrasil.</p></li><li><p>Run the tests to make sure everything works, then bump the LibSSH.jl version number and release \o/</p></li></ol></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../generated_changelog/">« Changelog</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Friday 11 October 2024 15:21">Friday 11 October 2024</span>. Using Julia version 1.11.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/examples/index.html

@@ -7,7 +7,7 @@
 
 host_key = ssh.get_server_publickey(session)
 sha256_hash = pki.get_publickey_hash(host_key)
-fingerprint = pki.get_fingerprint_hash(sha256_hash)</code></pre><pre><code class="nohighlight hljs">&quot;SHA256:Vf+1NFAbPNmkMgdwCB9q+PYXHOTZfol0OhBoBBBTrNc&quot;</code></pre><p>Or convert it to a hex string with <a href="../utilities/#LibSSH.get_hexa"><code>get_hexa()</code></a>:</p><pre><code class="language-julia hljs">hex = ssh.get_hexa(sha256_hash)</code></pre><pre><code class="nohighlight hljs">&quot;55:ff:b5:34:50:1b:3c:d9:a4:32:07:70:08:1f:6a:f8:f6:17:1c:e4:d9:7e:89:74:3a:10:68:04:10:53:ac:d7&quot;</code></pre><p>Since this is a dummy key from the demo server we don&#39;t really want to add it to our known hosts file, but if this was asked to the user and they said yes, it should be added to the known hosts using <a href="../sessions_and_channels/#LibSSH.update_known_hosts"><code>update_known_hosts()</code></a>. But since it&#39;s a dummy key let&#39;s just trust it and continue with authenticating ourselves to the server.</p><div class="admonition is-danger"><header class="admonition-header">Danger</header><div class="admonition-body"><p>Don&#39;t skip host verification. It&#39;s the only part of the protocol that libssh doesn&#39;t handle for you, and security cannot be guaranteed without it.</p></div></div><p>Since we created the server we already know that it supports password authentication, but a good client should check anyway:</p><pre><code class="language-julia hljs">ssh.userauth_list(session)</code></pre><pre><code class="nohighlight hljs">1-element Vector{LibSSH.AuthMethod}:
+fingerprint = pki.get_fingerprint_hash(sha256_hash)</code></pre><pre><code class="nohighlight hljs">&quot;SHA256:iFJLIfgwsHYkCjXcX0PTM1eQ6JiQdGfahP7YxmRyIaw&quot;</code></pre><p>Or convert it to a hex string with <a href="../utilities/#LibSSH.get_hexa"><code>get_hexa()</code></a>:</p><pre><code class="language-julia hljs">hex = ssh.get_hexa(sha256_hash)</code></pre><pre><code class="nohighlight hljs">&quot;88:52:4b:21:f8:30:b0:76:24:0a:35:dc:5f:43:d3:33:57:90:e8:98:90:74:67:da:84:fe:d8:c6:64:72:21:ac&quot;</code></pre><p>Since this is a dummy key from the demo server we don&#39;t really want to add it to our known hosts file, but if this was asked to the user and they said yes, it should be added to the known hosts using <a href="../sessions_and_channels/#LibSSH.update_known_hosts"><code>update_known_hosts()</code></a>. But since it&#39;s a dummy key let&#39;s just trust it and continue with authenticating ourselves to the server.</p><div class="admonition is-danger"><header class="admonition-header">Danger</header><div class="admonition-body"><p>Don&#39;t skip host verification. It&#39;s the only part of the protocol that libssh doesn&#39;t handle for you, and security cannot be guaranteed without it.</p></div></div><p>Since we created the server we already know that it supports password authentication, but a good client should check anyway:</p><pre><code class="language-julia hljs">ssh.userauth_list(session)</code></pre><pre><code class="nohighlight hljs">1-element Vector{LibSSH.AuthMethod}:
  AuthMethod_Password::AuthMethod = 2</code></pre><p>If we give the wrong password we&#39;ll get denied:</p><pre><code class="language-julia hljs">@assert ssh.userauth_password(session, &quot;quux&quot;) == ssh.AuthStatus_Denied</code></pre><p>But the right password should succeed:</p><pre><code class="language-julia hljs">@assert ssh.userauth_password(session, &quot;foo&quot;) == ssh.AuthStatus_Success</code></pre><p>Going through all the authentication methods can be quite complicated, in practice it may be easier to use <a href="../sessions_and_channels/#LibSSH.authenticate"><code>authenticate()</code></a> which will handle all of that for you.</p><h2 id="Running-commands"><a class="docs-heading-anchor" href="#Running-commands">Running commands</a><a id="Running-commands-1"></a><a class="docs-heading-anchor-permalink" href="#Running-commands" title="Permalink"></a></h2><p>Now that we&#39;re authenticated to the server we can actually do something, like running a command (see <a href="../sessions_and_channels/#Command-execution">Command execution</a>):</p><pre><code class="language-julia hljs">@assert read(`echo &#39;Hello world!&#39;`, session, String) == &quot;Hello world!\n&quot;</code></pre><h2 id="SFTP"><a class="docs-heading-anchor" href="#SFTP">SFTP</a><a id="SFTP-1"></a><a class="docs-heading-anchor-permalink" href="#SFTP" title="Permalink"></a></h2><p>LibSSH.jl allows reading and writing remote files with the same API as local files with <code>Base</code>. Lets start by making a temporary directory and creating a file in it &#39;remotely&#39;:</p><pre><code class="language-julia hljs">tmpdir = mktempdir()
 path = joinpath(tmpdir, &quot;foo&quot;)
 
@@ -19,4 +19,4 @@
 position(file)</code></pre><pre><code class="nohighlight hljs">0x0000000000000000</code></pre><pre><code class="language-julia hljs">isreadable(file)</code></pre><pre><code class="nohighlight hljs">false</code></pre><pre><code class="language-julia hljs">iswritable(file)</code></pre><pre><code class="nohighlight hljs">true</code></pre><p>After using it we have to close it explicitly because the finalizer won&#39;t do it for us (see the <a href="../sftp/#Base.close-Tuple{LibSSH.SftpFile}"><code>Base.close(::SftpFile)</code></a> docstring for details):</p><pre><code class="language-julia hljs">close(file)</code></pre><h2 id="Disconnecting"><a class="docs-heading-anchor" href="#Disconnecting">Disconnecting</a><a id="Disconnecting-1"></a><a class="docs-heading-anchor-permalink" href="#Disconnecting" title="Permalink"></a></h2><p>Now we can disconnect our client session:</p><pre><code class="language-julia hljs">close(sftp)
 close(session)</code></pre><p>And stop the server:</p><pre><code class="language-julia hljs">demo.stop(demo_server)</code></pre><pre><code class="nohighlight hljs">┌ Warning: Closing SshChannel failed with -1: &#39;Socket error: disconnected&#39;
 └ @ LibSSH ~/work/LibSSH.jl/LibSSH.jl/src/channel.jl:195
-</code></pre><p>Note that sometimes the <code>DemoServer</code> will display a warning that closing an <code>SshChannel</code> failed because of <code>Socket error: disconnected</code>. That can be safely ignored, it just means that the socket was closed on the client side before the server could close the <code>SshChannel</code>, but the <code>SshChannel</code> memory will still be freed. It typically happens when doing SFTP operations since the <a href="../sftp/#SftpSession"><code>SftpSession</code></a> manages its own <code>lib.ssh_channel</code>.</p><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« LibSSH.jl</a><a class="docs-footer-nextpage" href="../sessions_and_channels/">Sessions and Channels »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Thursday 10 October 2024 16:18">Thursday 10 October 2024</span>. Using Julia version 1.11.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+</code></pre><p>Note that sometimes the <code>DemoServer</code> will display a warning that closing an <code>SshChannel</code> failed because of <code>Socket error: disconnected</code>. That can be safely ignored, it just means that the socket was closed on the client side before the server could close the <code>SshChannel</code>, but the <code>SshChannel</code> memory will still be freed. It typically happens when doing SFTP operations since the <a href="../sftp/#SftpSession"><code>SftpSession</code></a> manages its own <code>lib.ssh_channel</code>.</p><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« LibSSH.jl</a><a class="docs-footer-nextpage" href="../sessions_and_channels/">Sessions and Channels »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Friday 11 October 2024 15:21">Friday 11 October 2024</span>. Using Julia version 1.11.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>