Поиск по сайту:

Технические рекомендации и передовой опыт для учебных пособий

Введение

Это руководство представляет собой попытку обобщить установившиеся передовые практики и настоятельные рекомендации для авторов руководств DigitalOcean. Он предназначен для обеспечения согласованности, технической правильности и простоты использования учебных материалов DigitalOcean.

Это руководство по своей природе является как незавершенным, так и самостоятельным документом, основанным на растущем опыте штатных технических писателей и редакторов, менеджеров сообщества и инженеров. Его рекомендации могут быть изменены и написаны специально для образовательного контента с учетом широкого круга читателей и конечных пользователей.

Источники программного обеспечения и установка

Многие учебники будут полагаться на существующие учебники в качестве предварительных требований. Поместите все предварительные требования для статьи (включая любые вложенные предварительные требования для предварительных условий) в статью, а не глубоко вложенные списки предварительных требований.

Предпочтительные источники

В грубом порядке убывания предпочтения используйте следующие механизмы установки:

  1. Рекомендуемый проектом метод, признанный лучшим. Многие проекты быстро меняются и рекомендуют выходить за рамки официальных репозиториев, но некоторые установки (например, шаблоны curl | bash) требуют решения, использовать их или нет.
  2. Официальные репозитории пакетов для текущего дистрибутива и выпуска.
  3. Официальные пакеты для конкретных языков (NPM, CPAN, PIP, RubyGems, Composer и т. д.)
  4. Репозитории пакетов для конкретных проектов (например, Nginx предоставляет собственные репозитории для актуальных версий) или, в Ubuntu, доверенный PPA. Убедитесь, что они получены из надежного источника, например от разработчиков проекта или сопровождающих пакетов Debian/Ubuntu.
  5. Двоичные файлы со страницы релизов проекта GitHub или аналогичного официального веб-источника.
  6. wget или curl установочные скрипты, переданные в оболочку, с соответствующим предупреждением о проверке скриптов.

Предпочтительные места установки

В общем, избегайте ненужных осложнений. Для неупакованного программного обеспечения, установленного из исходного кода или двоичных файлов, обычно следует принимать префикс установки по умолчанию, если только он не является очень необычным или вызывает конфликты.

Сценарий инициализации, соответствующий официальным рекомендациям по распространению, должен предоставляться для сервис-ориентированного программного обеспечения, если он не предусмотрен пакетом или другим способом установки.

В системах Linux поместите автономные двоичные файлы или каталоги в /opt, а отдельные сценарии — в /usr/local/bin.

Программное обеспечение и обслуживание системы

В системах Ubuntu и Debian должны быть установлены и настроены автоматические обновления как минимум с установленными и настроенными обновлениями безопасности. Мы рекомендуем не выполнять автоматическую перезагрузку или автоматическое обновление всего в зависимости от контекста.

Обычно мы рекомендуем использовать команду apt для Ubuntu 18.04 и новее. Измените apt-get и apt-cache, чтобы использовать apt. При обновлении подходящих команд не используйте флаг -y; читатели должны руководствоваться всеми необходимыми входными данными и подсказками.

Для учебных пособий CentOS и Rocky Linux мы теперь рекомендуем использовать dnf, который заменил yum и обеспечивает более высокую производительность.

Если руководство основано на последних обновлениях, вызовите update и upgrade во время установки на шаге 1 или по мере необходимости. Сначала вызовите update, чтобы ваш сервер загружал последние версии пакетов. Включая upgrade, который загружает и устанавливает новые версии для каждого пакета, имейте в виду, что некоторые пользователи могут оставить определенные пакеты в более низкой версии.

Управление услугами

Обязательно используйте собственные системные команды инициализации, даже если доступны устаревшие команды совместимости. Например, используйте sudo systemctl start [service_name], хотя sudo service [service_name] start будет работать.

Предоставьте информацию о том, как включить или отключить запуск службы при загрузке. Укажите, как проверять результаты команд, связанных со службой, если это не указано явно в интерфейсе (journalctl -u, systemctl status и т. д.).

Как правило, предпочитайте перезапуски перезагрузкам для служб. В большинстве случаев более важно обеспечить известное состояние, чем избежать прерывания службы на доли секунды, а перезапуски также более полезны в случае полного сбоя службы.

Системы начальной загрузки

Если это не часть рабочего процесса управления конфигурацией, в большинстве случаев отдавайте предпочтение сценариям пользовательских данных и сценариям cloudinit, а не сценариям bash в пользовательских данных.

Регистрация и устранение неполадок

Объясните, где и как получить доступ к журналам установленных служб. При необходимости объясните команды systemctl и journalctl для проверки состояния службы и вывода журнала. По возможности предлагайте краткие предложения по диагностике типичных случаев отказа.

Обязательно обрабатывайте ротацию журналов для всех случаев, когда она не обрабатывается пакетами или другими механизмами установки.

Для следующих файлов журналов с открытым текстом используйте tail -F, а не tail -f, так как последний не будет отслеживать файл при переименовании и может вызвать путаницу, если журналы чередуются во время пользователь наблюдает за ними.

Управление пользователями и группами

Создайте пользователей sudo вместо прямого использования root. Обратитесь к соответствующим руководствам по начальной настройке сервера, в которых эта задача описана как предварительное условие.

В дистрибутивах на основе Debian добавляйте и удаляйте пользователей с помощью adduser sammy и deluser --remove-home sammy соответственно; в дистрибутивах на основе RHEL используйте adduser sammy (при необходимости установите пароль с помощью passwd sammy) и userdel -r sammy.

Предоставьте привилегии sudo с помощью usermod -aG sudo sammy в Ubuntu. CentOS немного сложнее. В современных версиях используется usermod -aG wheel sammy, но в некоторых версиях требуется, чтобы visudo сначала раскомментировал разрешения группы wheel. В частности, в CentOS 5 необходимо установить sudo и раскомментировать группу колес с помощью visudo; в CentOS 6 sudo уже установлен, но колесо нужно раскомментировать; В CentOS 7 есть sudo, и группа колес уже настроена.

При использовании команд с повышением привилегий обязательно проверяйте их в том виде, в каком они написаны. Чтобы передать переменные среды через sudo, используйте sudo -E command_to_run (если доверена вся среда) или sudo FOO=BAR command_to_run. Для экземпляров, которым требуется корневая оболочка, используйте sudo -i. Для экземпляров, требующих перенаправления, используйте tee -a для добавления, а не замены целевого файла: [sudo] command_to_run | sudo tee [-a] file_to_change.

Предпочтительные инструменты

Для интерактивных оболочек предположим, что Bash в системах GNU/Linux упоминается явно, когда это уместно. Во FreeBSD используйте tcsh, так как он доступен из коробки и имеет полезные функции.

Для текстовых редакторов мы включаем копирование «использовать [предпочтительный] или ваш любимый текстовый редактор» и включаем следующие удобные для начинающих редакторы в команды для копирования и вставки. В Linux по умолчанию используется nano; в FreeBSD мы по умолчанию используем ee. vi(m) допустим, но избегайте его во вводных темах, где он может стать камнем преткновения для начинающих.

Для передачи файлов мы обычно рекомендуем использовать sftp в большинстве случаев для его интерактивного и похожего на scp использования, хотя в нем отсутствуют функции push, поэтому scp также приемлем. rsync полезен для резервного копирования и передачи больших файлов (или множества маленьких файлов). Не используйте FTP ни при каких обстоятельствах. Мы также стараемся стандартизировать curl вместо wget из-за его надежности. Преимущество wget в основном заключается в рекурсивной загрузке (т.е. особый вариант использования, который не характерен для нашего контента).

На машинах, поставляемых с утилитами iproute2, мы предпочитаем их набору net-tools, который считается устаревшим. В целом, утилиты iproute2, такие как ss, будут иметь лучшую поддержку нескольких интерфейсов, IPv6, новых функций ядра и т. д. Таким же образом мы должны использовать ip route поверх route, ip addr show поверх ifconfig и т. д. Иногда вывод старых утилит по умолчанию немного чище, но сам вывод немного менее заслуживают доверия, поскольку они также не обрабатывают пограничные случаи. Когда это возможно, мы будем управлять более подробным выводом, используя доступные флаги.

Сценарии

В контексте руководств по системному администрированию обычно избегайте длинных пользовательских сценариев и длинных сценариев оболочки.

Написанные автором сценарии (и, возможно, другие ресурсы) должны храниться в репозитории каждой статьи в учетной записи GitHub сообщества do-community со ссылкой на опубликованное руководство. Следуйте хорошей практике написания сценариев в целом. Например, поместите любые переменные, которые пользователь должен будет заполнить, в верхней части скрипта, предпочтительно в хорошо выделенном разделе. Предоставляйте встроенные комментарии там, где это необходимо для создания удобочитаемых сценариев. Убедитесь, что ваши описания кода представлены не только в комментариях, но и в прозаических описаниях с дополнительными пояснениями, чем в комментариях.

Предпочитайте /bin/sh bash и избегайте специфичных для Bash функций, когда проблема переносимости или кросс-платформенного повторного использования. Используйте оболочку и coreutils/стандартные инструменты Unix для небольших задач; избегайте введения новых зависимостей исключительно для задач связующего языка, если преимущества не являются существенными. Вместо #!/path/to/interpreter используйте #!/usr/bin/env интерпретатор.

Как правило, для планирования повторяющихся задач используйте cron, но системные таймеры также допустимы.

Расположение файловой системы

По возможности используйте your_server_ip и your_domain вместо диапазонов IP-адресов в документации или example.com.

При загрузке скриптов или данных убедитесь, что пользователь находится в доступном для записи каталоге или что пути указаны явно. Для файлов, которые должны быть доступны для ссылки или повторного использования, используйте домашний каталог пользователя, если только они не принадлежат какому-либо стандартному четко определенному пути в другом месте файловой системы (например, /opt или /etc). Для одноразовых файлов используйте /tmp.

Если учебник опирается на определенный каталог, обязательно предоставьте команды cd, которые направляют ридер в этот каталог перед выполнением команд.

Веб-серверы

Мы рекомендуем каталоги конфигурации в стиле Debian для дистрибутивов, которые не имеют такой структуры по умолчанию. Всегда проверяйте изменения конфигурации (Apache использует sudo apachectl configtest, а Nginx использует sudo nginx -t).

Для руководств по Apache или Nginx используйте выделенные блоки виртуальных хостов вместо редактирования файлов конфигурации по умолчанию. Этот маршрут позволяет избежать распространенных ошибок и сохранить файлы по умолчанию в качестве резервной конфигурации, как и предполагалось.

Безопасность

Шифровать и аутентифицировать все соединения между системами. Не поощряйте (явно или неявно) пользователей отправлять учетные данные или передавать закрытые данные в открытом виде.

В частности, пароли и ключевые материалы не должны передаваться по незащищенным соединениям. Соединения с базой данных, ведение журналов, управление кластером и другие службы в идеале должны быть всегда зашифрованы.

Веб-панели управления должны обслуживаться через соединения HTTPS, а TLS/SSL следует использовать для служб, где они поддерживаются. Все веб-серверы должны быть с поддержкой HTTPS (или, по крайней мере, способными). Используйте предварительное условие certbot для предоставления сертификата SSL. Общедоступные сервисы, такие как простой HTTP, разрешены, поскольку пользователи могут по-прежнему хотеть или должны предлагать их, но в общем случае их использование настоятельно не рекомендуется, особенно для динамического контента. Для статей, которые обеспечивают простое HTTP-соединение, добавьте примечание или предупреждающую метку, чтобы препятствовать обычному HTTP и поощрять HTTPS.

Избегайте методов, которые обеспечивают безопасность с низкими преимуществами из-за неясности или театральности, таких как изменение порта SSH по умолчанию. Настройте брандмауэр. Наши рекомендации для конкретных дистрибутивов: ufw для Ubuntu, iptables для Debian и firewalld для CentOS. Тем не менее, iptables наиболее согласован на разных платформах и имеет множество инструментов, которые к нему подключаются.

SSH

Поддерживайте порт SSH по умолчанию в качестве нормы. Изменение порта следует выполнять только в определенных ситуациях, когда это является первостепенной задачей.

Отключите аутентификацию по паролю и используйте аутентификацию только по ключу для root или, в качестве альтернативы, полностью отключите вход в систему root. Используйте надежные ключи SSH: RSA не менее 2048 бит, но рекомендуется 4096; ECDSA больше не рекомендуется по техническим причинам; алгоритмы Ed25519 и эллиптических кривых недостаточно широко поддерживаются.

Используйте парольные фразы для любых интерактивных ключей, но не для неинтерактивных процессов. Настройте или скопируйте и измените владельца ключей SSH из учетной записи root в домашний каталог пользователя. Установите fail2ban там, где это практично.

Обратите внимание, что хотя переадресация агента SSH необходима для обычных рабочих процессов на таких платформах, как CoreOS, она сопряжена с некоторыми проблемами безопасности. По сути, любой, у кого есть права на вашем хосте, сможет использовать сокет переадресации для подключения к вашему локальному ssh-агенту.

SSL/TLS

Мы настоятельно рекомендуем использовать Let’s Encrypt для простоты использования и рекомендуем TLS. Используйте надежную защиту SSL; посмотрите на https://cipherli.st/ (как современные, так и устаревшие рекомендации).

Для хостов без доменного имени мы предлагаем самозаверяющий сертификат достаточной силы. Опять же, посмотрите на Nginx.

VPN

Мы рекомендуем VPN в качестве решения для общего зашифрованного обмена данными между серверами. Виртуальные частные сети становятся все более ценными, когда необходимо защитить несколько сервисов между серверами; вместо того, чтобы шифровать каждую услугу по отдельности, вся внутренняя связь может быть передана в VPN. Этот подход особенно полезен, если рассматриваемые сервисы не поддерживают собственное шифрование.

Обычно мы рекомендуем Tinc вместо OpenVPN для связи между серверами. Вы можете прочитать эту статью об Ansible и Tinc для более подробной информации и реализации.

Заключение

Это по своей сути самоуверенный, живой документ, который будет часто обновляться. Технологии быстро меняются, и мы в DigitalOcean делаем все возможное, чтобы не отставать, но если вы заметите какие-либо ошибки или у вас есть отзывы, мы будем следить за комментариями ниже.