Файл README на сервере: письмо себе через год

Вчера вечером полез обновлять свою маленькую VPS. Поднимал её прошлой осенью под три задачи: rsync-бэкап домашнего архива, проверка доступности одного сайта и скрипт, который шлёт уведомления в телеграм. Обновил пакеты, заглянул в crontab, чтобы ничего не сломать после перезапуска, и увидел строку:

0 4 * * * /opt/sync/run.sh >/dev/null 2>&1

Что такое /opt/sync, я не помнил. Внутри скрипт на несколько десятков строк, без единого комментария. Он забирает что-то по адресу, который мне ничего не говорит, и складывает в каталог, о котором я тоже забыл. Вывод уходит в /dev/null, поэтому даже не видно, отработал ли он хоть раз за последний месяц. Автор скрипта — я. Год назад мне всё было очевидно.

В итоге разобрался: остаток старой схемы бэкапа, который давно ничего не делал, потому что источник переехал. Но вывод отсюда другой. На сервере, который обслуживает один человек, документацией обычно служит его память. Память — плохое хранилище: в ней нет поиска, нет истории, и она не переживает отпуск.

С тех пор на каждой машине лежит один файл, /root/README.md. Не вики, не отдельная система, просто текст рядом с тем, что он описывает. Структура у меня такая.

1. Зачем этот сервер. Одна-две строки. «Бэкапы домашнего архива и мониторинг сайта». Если назначение не укладывается в две строки, это уже повод подумать.

2. Что запущено и почему. Каждая служба, каждый таймер, каждая строка cron — с пояснением, что она делает и что сломается, если её выключить. Последнее важнее первого: через год вопрос будет звучать именно так — можно ли это убрать.

3. Где лежат данные. Каталоги, базы, тома Docker, если есть. Что из этого нужно бэкапить, а что пересоздаётся.

4. Где секреты. Не сами пароли и ключи, а указание, где они хранятся: «токен бота в /etc/myapp/env, права 600». README читается чаще, чем нужно, и иногда не тем человеком.

5. Журнал изменений. Дата и одна строка. «Открыл порт для мониторинга», «перенёс бэкап с cron на systemd-таймер». Без подробностей, только чтобы было за что зацепиться.

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

systemctl list-units --type=service --state=running
systemctl list-timers
crontab -l
ls /etc/cron.d/
ss -tlnp
ls /etc/systemd/system/

Первая показывает работающие службы, вторая — таймеры systemd, которые многие забывают проверить, потому что ищут только в cron. ss -tlnp — какие порты слушаются и каким процессом. Последняя — юниты, которые добавлены руками, а не пришли с пакетами. Для crontab -l учтите, что у каждого пользователя свой, поэтому смотреть надо от того пользователя, под которым задачи создавались. Если Docker стоит, сюда же docker ps и список томов.

Каждую строку из этого вывода, которую вы не можете объяснить одной фразой, стоит разобрать до конца. Именно там обычно и живёт мой /opt/sync.

Две мелочи, которые помогают файлу не умереть.

Первая: напоминание при входе. В Debian и Ubuntu есть /etc/motd, его содержимое показывается после логина по SSH. Одна строка «Перед изменениями — /root/README.md» работает лучше, чем любые обещания себе. Правка требует root, но ничего не ломает.

Вторая: не глушить вывод скриптов в /dev/null. Если не хочется писем от cron, пусть пишет в файл, например:

0 4 * * * /opt/sync/run.sh >>/var/log/sync.log 2>&1

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

Правило обновления простое: изменил что-то на сервере — дописал строку в журнал до того, как закрыл SSH. Потом не допишется никогда.

Это не про большую инфраструктуру, там свои инструменты. Это про одну-две VPS, которые человек поднял для себя и не трогает месяцами. Интересно, кто как решает то же самое: держите заметки прямо на сервере или отдельно, в репозитории или менеджере паролей? У файла на сервере есть очевидный минус — он пропадёт вместе с машиной, и я пока не решил, насколько это критично.

lexa92 писал:
Память — плохое хранилище: в ней нет поиска, нет истории, и она не переживает отпуск.

Я бы в этот README первой строкой вписал не «зачем», а «кто платит и до какого числа». Мёртвый скрипт в /dev/null хотя бы бесплатный: молчит и молчит. А сервер, про который помнишь только «там что-то с бэкапом», так же молча продлевается каждый месяц) Год такой забывчивости — двенадцать платежей за машину, которая чинит давно уехавший источник.

ща, про «кто платит» прям в точку. у меня сервера пока нет, но с первой карты два месяца списывалось за приложение для заметок, которое я ставил ради одной лекции) заметок там ноль, то есть README у меня был пустой и платный. теперь в телефоне держу списочек: что, сколько, какого числа списание. если всё-таки возьму сервак под чатгпт с телефона, допишу его туда же, а не в память. она у меня до сессии живёт, дальше всё

timur_ufa писал:
она у меня до сессии живёт, дальше всё

Это я каждый год вижу у учеников: конспект пишут к экзамену, а не себе через год. С материалами курса у меня было так же. Открываю прошлогоднюю папку, а там «итог_финал_2» и ни слова, почему вышел именно он. Теперь в каждой папке лежит короткая записка: что поменяла, зачем и что не сработало. Ваш списочек в телефоне — такая же записка, только про деньги. Хорошая привычка, держитесь её.

«Что не сработало» в такой записке ценнее всего. И копию README держите не только на самом сервере. Умрёт диск, и письмо себе уйдёт вместе с ним.

anna_edu писал:
что поменяла, зачем и что не сработало

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

nesterov, копия на стороне через полгода превращается во второе письмо, уже другое. Лучше держать README в git и пушить на другую машину. Тогда копия одна, а история правок идёт в комплекте.

quiet_fox писал:
Без даты «не сработало» через год читается как «не работает»

В редакции это называется «цитата без даты»: человек сказал так в 2019-м, а мы подаём как сегодняшнее. С сервером для расшифровки у меня та же ловушка. В заметках висит «большая модель не влезла», и я уже не помню, на каком тарифе и с какой длиной записи. Так что к дате я бы дописывала условия: что было под рукой, когда не сработало. Иначе дата есть, а проверить нечего.