<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/content/features/disable-symlinks.md - fork/static-web-server @ allow-symlink</title>
<meta name="description" content="docs/content/features/disable-symlinks.md in fork/static-web-server at allow-symlink.">
<meta property="og:title" content="docs/content/features/disable-symlinks.md - fork/static-web-server @ allow-symlink">
<meta property="og:description" content="docs/content/features/disable-symlinks.md in fork/static-web-server at allow-symlink.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="allow-symlink" data-tip="4414610fe1b0370ff0ac415e9367548840584710">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/static-web-server</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/static-web-server</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Jose Quintana</span><span class="commit-message" data-commit="8451cf75b5d5932964a1ab9501ae8ae3c9874bf0">fix: disable symlinks option does not work properly (#639)</span><span class="snapshot-sha sha" data-commit="8451cf75b5d5932964a1ab9501ae8ae3c9874bf0">8451cf7</span><time datetime="2026-03-15T01:30:53+01:00" title="2026-03-15 01:30:53 +0100">2026-03-15</time></p>
<header class="topbar"><details class="switcher"><summary>allow-symlink</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/static-web-server/ref/allow-symlink/">allow-symlink</a><a class="all" href="/fork/static-web-server/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/static-web-server/">static-web-server</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/">docs</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/content/">content</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/content/features/">features</a> / <span class="cur">disable-symlinks.md</span></nav>
<span class="view-stats"><span>1.4 KiB</span><span>23 lines</span></span><span class="actions"><a class="raw" href="/fork/static-web-server/raw/a8b4c5e522ea90be5223183edc6fe1c09f8242dc/docs/content/features/disable-symlinks.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Disable Symlinks</h1>
<p><strong><code>SWS</code></strong> <em>does not</em> follow symlinks by default for security reasons.</p>
<p>As a result, SWS will respond with a <code>403 Forbidden</code> status if a symlink is requested as well as it won't be shown in the directory listing if enabled.</p>
<p>This feature is enabled by default and can be controlled by the boolean <code>--disable-symlinks</code> option or the equivalent <a href="/fork/static-web-server/ref/allow-symlink/blob/docs/content/configuration/environment-variables.md#server_disable_symlinks">SERVER_DISABLE_SYMLINKS</a> env.</p>
<p>!!! info "Possible performance impact for large paths"</p>
<pre><code>Take into account that when `disable-symlinks` is enabled (`--disable-symlinks=true` by default in SWS), the server will check if the whole requested path is a symlink or contains intermediate symlink components.
This involves filesystem access (syscall) for verification of each path component. Therefore, depending on the depth of the path, it may require multiple file system calls.

If this feature results in a _noticeable_ negative performance impact (e.g., large paths), then you could consider turning the feature off. If doing so, remember that SWS will allow symlinks in the webroot, but it won't follow them if they resolve outside of it, which is SWS's behaviour regardless of this feature.
</code></pre>
<p>Here is an example of how to enable symlinks following if wanted:</p>
<pre class="language-bash"><a-f>static-web-server</a-f> \
    <a-co>-p=8787</a-co> <a-co>-d=./public</a-co> <a-co>-g=trace</a-co> \
    <a-co>--directory-listing</a-co> \
    <a-co>--disable-symlinks=false</a-co></pre>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Disable Symlinks</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">**`SWS`** *does not* follow symlinks by default for security reasons.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">As a result, SWS will respond with a `403 Forbidden` status if a symlink is requested as well as it won&#39;t be shown in the directory listing if enabled.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">This feature is enabled by default and can be controlled by the boolean `--disable-symlinks` option or the equivalent [SERVER_DISABLE_SYMLINKS](./../configuration/environment-variables.md#server_disable_symlinks) env.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">!!! info &quot;Possible performance impact for large paths&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-tl>    Take into account that when `disable-symlinks` is enabled (`--disable-symlinks=true` by default in SWS), the server will check if the whole requested path is a symlink or contains intermediate symlink components.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>    </a-p><a-tl>This involves filesystem access (syscall) for verification of each path component. Therefore, depending on the depth of the path, it may require multiple file system calls.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-tl>    If this feature results in a _noticeable_ negative performance impact (e.g., large paths), then you could consider turning the feature off. If doing so, remember that SWS will allow symlinks in the webroot, but it won&#39;t follow them if they resolve outside of it, which is SWS&#39;s behaviour regardless of this feature.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">Here is an example of how to enable symlinks following if wanted:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"><a-p>```</a-p><a-tl>sh</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>static-web-server \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>    -p=8787 -d=./public -g=trace \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"><a-p>    --directory-listing \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>    --disable-symlinks=false</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>```</a-p></span></span></pre></div></div>
</main>
</body>
</html>
