web-shared-folder/README_RUS.md

Web server for sharing folder on local network or Internet

# web-shared-folder
Удобный http-сервер на nodejs. Предназначен для того, чтобы делиться файлами и папками в локальной сети или даже в Интернете через веб интерфейс. Также может использоваться как веб-сервер для обслуживания статических сайтов.

## Возможности
* Общедоступная директория в локальной сети или Интернете через веб интерфейс.
* Есть возможность не только скачивания данных из заданной папки, но и загрузки в неё.
* Можно создавать пользователей с доступом только к заданной папке.
* Может работать в качестве сервера для обсллуживания статического web-сайта.
* Есть возможность работать по протоколу HTTPS.
* Если высокая нагрузка, то можно включить режим кластера, задействуя все ядра серверной машины.
* Есть тёмная тема.
* Интерфейс на нескольких языках (пока есть только английский и русский).

## Установка

```
npm i -g web-shared-folder
```

## Запуск

```
wsf </path/to/folder/for/sharing> <port> [</path/to/key> </path/to/cert>] [--upload or -u]
```

Для вывода только номера версии:

```
wsf -v [or --version]
```

Для вывода справки:

```
wsf -h [or --help]
```

Для вывода информации о лицензии:

```
wsf -l [or --license]
```

Вместо `wsf` для запуска можно использовать полное имя программы `web-shared-folder`

## Базовая работа

Для работы сервера минимально требуется указать путь к директории, которую нужно расшарить и номер порта, на котором будет работать сервер. Путь к папке указывается в первом параметре. Далее указывается номер порта.

Сервер web-shared-folder работает следующим образом:
Если в корне указанной директории есть файл index.html, то web-shared-folder начинает работать как web-сервер, который обслуживает статический сайт и при запросе на корневой URL отдаст index.html. В противном случае сервер переходит в режим отображения содержимого указанной в параметрах запуска директории. В этом случае пользователь может скачивать находящиеся в этой директории файлы и папки.

Пример:

```
wsf . 80
```

Если в текущей папке нет файла index.html, тогда эта команда запустит сервер на 80 порту и расшарит для обзора и скачивания текущую папку.
Сервер будет доступен на всех имеющихся сетевых интерфейсах (это можно изменить через задание соответствующей переменной окружения). Например, пусть сервер имеет ip-адрес 192.168.1.2, тогда для доступа в локальной сети в браузере можно набрать адрес http://192.168.1.2. Т.к. используется стандартный номер порта 80, то в адресе номер порта не указывается. При использовании нестандартного номера порта, например 8080, его необходимо указывать в адресе: http://192.168.1.2:8080. На линукс машинах для работы с портом 80 возможно потребуется запускать сервер от root.

![Скриншот: загрузка на сервер запрещена](https://github.com/Mendeo/web-shared-folder/blob/master/img/screenshot_upload_disabled.png)  
*Загрузка на сервер запрещена*

Ссылка в виде глаза напротив файла, позволяет открыть его прямо в браузере в отдельной вкладке. Так можно просматривать, например текст, фотографии или некоторые видео (если кодировку поддерживает браузер).

Если же требуется дать возможность пользователям закачивать файлы на сервер в расшаренную папку, а также иметь возможность переименовывать удалять и перемещать имеющиеся файлы и папки, то сервер web-shared-folder должен запускаться с ключом --upload или -u.

Однако, на закачку файлов имеются ограничения. Дело в том, что загружаемые файлы передаются в одном запросе к серверу и в браузерах существует ограничение на длительность такого запроса, обычно 5 или 10 минут (в зависимости от браузера). Если длительность закачки превысит это время, то она завершится с ошибкой. Ещё одним ограничением является общий размер загружаемых за один раз файлов. Он не должен превышать 2 ГиБ.

Пример:

```
wsf . 80 -u
```

![Загрузка на сервер разрешена](https://github.com/Mendeo/web-shared-folder/blob/master/img/screenshot_upload_enabled.png)  
*Загрузка на сервер разрешена*

В этом режиме нажатие на ссылку в виде стрелки вверх напротив zip архива приведёт к распаковке этого архива в текущую директорию.

## Работа через HTTPS

Для работы через HTTPS требуется указать путь к файлу секретного ключа ssl (обычно privkey.pem) и путь к файлу ssl сертификата (обычно fullchain.pem).

Пример:

```
wsf . 443 /etc/ssl/privkey.pem /etc/ssl/fullchain.pem
```

или с включённой возможностью закачки:

```
wsf . 443 /etc/ssl/privkey.pem /etc/ssl/fullchain.pem -u
```

В примерах выше используется стандартный номер порта для работы по протоколу HTTPS - 443. Файлы секретного ключа и сертификата обычно выдаются центрами сертификации - организации, которые обладают правом выдачи цифровых SSL сертификатов. Но можно также сгенерировать самоподписанный сертификат, например при помощи openssl, однако в этом случае браузер будет выдавать предупреждение.

## Переменные окружения

Более тонкая настройка сервера уже ведётся через задания переменных окружения.
Прежде всего, в эти переменные можно записать аргументов командной строки, описанные выше и запускать сервер вовсе без дополнительных аргументов.

Ниже представлена таблица с описанием всех возможных переменных окружения.

### Базовые переменные

Переменная окружения                  |Описание
:-------------------------------------|:-
WSF_ROOT                              |Путь к папке, которую нужно сделать общедоступной.
WSF_PORT                              |Порт, который сервер будет слушать.
WSF_UPLOAD_ENABLE                     |Переводит сервер в режим, в котором пользователь может загружать свои файлы в общедостпную папку, а также перемещать, переименовывать и удалять файлы и папки в ней.
WSF_DIRECTORY_MODE                    |Если в корневой папке есть файл `index.html`, то сервер по умолчанию запускается в режиме отображения веб страницы, связанной с `index.html`, а не в режиме отображения содержимого директории. Для принидительного переключения на режим отображения содержимого директории следует задать `WSF_DIRECTORY_MODE=1`.
WSF_DIRECTORY_MODE_TITLE              |Задаёт заголовок страниц, который отображается на вкладке в браузере. По умолчанию отображается "Удалённый менеджер файлов".

### Работа через HTTPS

Переменная окружения                  |Описание
:-------------------------------------|:-
WSF_CERT                              |Путь к файлу ssl сертификата (обычно `fullchain.pem`).
WSF_KEY                               |Путь к файлу секретного ключа ssl (обычно `privkey.pem`).
WSF_AUTO_REDIRECT_HTTP_PORT           |Когда сервер работает в защищённом режиме (по протоколу HTTPS), то есть возможность включить автоматическую переадресацию клиентов, пытабхихся подключиться по протоколу HTTP. Например, пусть сервер работает на стандартном для HTTPS порту 443. Требуется сделать автоматическое перенаправление клиентов, подключающихся по HTTP (стандартный порт 80), для этого задаётся `WSF_AUTO_REDIRECT_HTTP_PORT=80`.

### Настройки безопасности

Переменная окружения                  |Описание
:-------------------------------------|:-
WSF_ALLOWED_INTERFACES                |Список интерфейсов, на которых будет доступен сервер. По умолчанию сервер будет доступен на всех доступных сетевых интерфейсах, однако это не желательно, если требуется, например, ограничить доступ из внешней сети. В этой переменной задаётся список ip адресов (через запятую), на которых будет работать сервер. Например, чтобы был доступ только для localhost можно задать `WSF_ALLOWED_INTERFACES=127.0.0.1`.
WSF_FORBIDDEN_PATHS                   |Список путей, относительно корневой директории, которые не будут отображаться у клиентов. Пути отделяются символом двоеточия `:` Например, уберём из отображения папку `.git` и `secret`: `WSF_FORBIDDEN_PATHS=.git:secret`.

### Создание пользователей и ограничений доступа

Переменная окружения                  |Описание
:-------------------------------------|:-
WSF_USERS                             |Задание этой переменной среды переводит сервер в режим, в котором доступ к файлам доступен лишь для заданных пользвателей. Формат этой переменной следующий: имя пользователя, затем символ `@`, далее sha256 хэш пароля (hex) пользователя, затем путь, к которому будет иметь доступ пользователь, далее двоеточие `:` и аналогиченые данные для других пользователей. Путь должен начинаться с символа `/`, он должен задаваться относительно корневой директории и указывать на папку. Если в пути есть ошибки, то это станет заметно только при попытке входа пользователя. Пример: `username1@sha256password1InHex/path1/relative/ROOT_PATH:username2@sha256password2InHex/path2/relative/ROOT_PATH`. **Следует обратить внимание, что работа в данном режиме по протоколу HTTP небезопасна, т.к. имена пользователей и пароли передаются по сети в открытом виде и могут быть легко перехвачены. Чтобы безопасно работать в этом режиме, используйте HTTPS. В этом случае, даже с использованием самоподписанного SSL сертификата, обмен данными с сервером будет зашифрован.**
WSF_SESSION_TIMEOUT                   |Время сессии пользователя (в секундах). В случае неактивности пользователя в течении этого времени, сессия завершается и при повтороном запросе потребуется снова ввести логин и пароль. По умолчанию это время равно 30 минутам.
WSF_SESSION_UPDATE_PAUSE_MILLISECONDS |Время (в миллисекундах), в течение которого сессия не будет пролеваться, даже если от пользователя приходят запросы. По умолчанию значение равно 5000 мс.

![Запрос на ввод имени пользователя и пароля](https://github.com/Mendeo/web-shared-folder/blob/master/img/screenshot_authentication_required.png)  
*Запрос на ввод имени пользователя и пароля*

### Работа в режиме кластера

Переменная окружения                  |Описание
:-------------------------------------|:-
WSF_USE_CLUSTER_MODE                  |Переводит сервер в режим работы в виде кластера. В этом режиме запускается несколько копий серверного процесса (рабочие процессы по числу ядер процессора), и нагрузка будет распределена на эти процессы, что позволяет в полной мере задействовать ресуры процессора и увеличить производительность сервера при большом числе запросов к нему. Но этот режим также требует большого количества оперативной памяти. В тоже время, этот режим делает работу сервера более устойчивой, т.к. при задании переменной `WSF_SHOULD_RESTART_WORKER` в случае сбоев в работе серверных процессов, они будут автоматически перезапущены.
WSF_SHOULD_RESTART_WORKER             |Нужно ли перезапускать рабочие процессы в режиме кластера в случае их непредвиденного завершения. По умолчанию эти процессы не перезапускаются.

### Настройка внешнего вида

Переменная окружения                  |Описание
:-------------------------------------|:-
WSF_ICONS_TYPE                        |Web-shared-folder использует [file-icon-vectors](https://www.npmjs.com/package/file-icon-vectors) npm пакет, чтобы отображать иконки файлов и папок. Доступно всего три варианта этих иконок: `classic`, `square-o`, `vivid`. Можно установить `WSF_ICONS_TYPE` на один из этих вариантов. По умолчанию используется `square-o`.

### Прочие настройки

Переменная окружения                  |Описание
:-------------------------------------|:-
WSF_DISABLE_COMPRESSION               |Позволяет принудительно отключить сжатие файлов при передаче по сети. Требуется для целей отладки и на отображение в браузере не влияет.
WSF_SHOW_SYSTEM_FILES_REQUESTS        |Заставляет выводить в логи не только запросы к расшаренным файлам, но и запросы к файлам самого приложения web-shared-folder, находящиеся по пути /wsf_app_files, например к /wsf_app_files/favicon.icon и др.