Linux: rsync code 23 — практическая диагностика partial transfer, прав, symlinks и vanished files

Код возврата 23 у rsync — одна из самых частых и одновременно самых неудобных ошибок в админской практике. Формально это partial transfer due to error, то есть передача выполнена частично из-за ошибки. Проблема в том, что сам код слишком общий: под ним могут скрываться недоступные файлы, битые симлинки, исчезнувшие по ходу копирования объекты, ошибки прав, проблемы с владельцами, ACL, xattrs и обычная гонка с приложением, которое в этот момент чистит кэш или перекладывает логи.

Именно поэтому rsync code 23 почти никогда не лечится одной универсальной командой. Рабочий подход другой: быстро сузить круг причин и понять, что именно ломает передачу. На практике чаще всего виноваты три сценария: permissions, symlinks и vanished files.

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

Ниже разберём практический алгоритм диагностики для Debian, Ubuntu, AlmaLinux, Rocky Linux и похожих систем.

Что на самом деле означает rsync code 23

Строго говоря, диагностика при коде 23 должна начинаться не с самой цифры, а с текста ошибок выше по выводу. Именно строки вида rsync: ... failed: Permission denied (13), No such file or directory (2), symlink has no referent или file has vanished и дают реальную причину.

Типичная ошибка — смотреть только на последнюю строку:

rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(...)

Сама по себе она почти бесполезна. Нужен весь контекст перед ней. Поэтому первый шаг всегда один: запускать rsync так, чтобы видеть подробный список проблемных объектов, а не только финальный код возврата.

Базовый алгоритм диагностики без гадания

Если rsync завершился с кодом 23, удобно идти по короткому маршруту:

1. Повторить запуск вручную с подробным выводом.
2. Вытащить все строки rsync: и сгруппировать их по типу ошибки.
3. Проверить, это проблемы чтения, записи, симлинков или исчезающих файлов.
4. Оценить, затрагивают ли ошибки критичные данные или только временный мусор.
5. После этого менять команду, права или список исключений.

Для ручной диагностики подойдёт такой запуск:

rsync -avHAX --numeric-ids --delete --itemize-changes --stats /src/ /backup/

Если копирование идёт по SSH:

rsync -avHAX --numeric-ids --itemize-changes -e ssh /src/ backup@host:/backup/

Если нужно собрать лог и потом отфильтровать причины:

rsync -avHAX --numeric-ids --itemize-changes /src/ /backup/ > /tmp/rsync.log 2>&1
grep '^rsync:' /tmp/rsync.log

Уже на этом этапе обычно становится видно, куда копать дальше. Если вы строите резервные копии по SSH, пригодится и отдельный разбор подходов в статье про rsync по SSH для backup и deploy.

Чаще всего виноваты права и file ownership

Самый распространённый сценарий — процесс rsync не может прочитать часть источника или записать часть приёмника. В логе это выглядит как Permission denied (13) или как ошибки установки владельца, группы, времён, ACL и extended attributes.

Типичные причины такие:

• запуск от пользователя, у которого нет доступа к части дерева;
• попытка сохранить owner и group без root-прав;
• копирование системных каталогов с ACL и xattrs без достаточных привилегий;
• запись в целевой каталог, где не хватает прав или места под временные файлы;
• рассинхрон UID и GID между источником и приёмником.

Посмотрите владельца и права проблемного объекта:

namei -l /src/path/to/file
stat /src/path/to/file

Команда namei -l особенно полезна, потому что показывает права не только конечного файла, но и всех каталогов по пути. На практике часто выясняется, что сам файл читается, а один из промежуточных каталогов закрыт по x или r.

Если ошибка связана именно с владельцем и группой, в выводе часто есть что-то вроде:

rsync: chown "/backup/path/file" failed: Operation not permitted (1)

Это значит, что содержимое могло скопироваться, но метаданные не применились. Для обычного пользовательского бэкапа это может быть некритично, а для точного восстановления системы — уже важно.

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

rsync -a /src/ /backup/
rsync -rlptD /src/ /backup/

Отдельно проверяйте ACL и xattrs, если работаете с системными каталогами, контейнерными томами или данными приложений:

getfacl /src/path/to/file
getfattr -d /src/path/to/file

Если в сообщениях фигурируют Permission denied, Operation not permitted, failed to set permissions, chgrp или chown, сначала разбирайте права и ownership, а не сеть и не SSH.

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

Как отличить реальные проблемы прав от нормального поведения без root

Многие пугаются, когда видят code 23 в пользовательском бэкапе домашнего каталога на удалённый сервер. Но если задача запускается не от root, попытка сохранить владельца и группу на удалённой стороне часто заранее обречена. Это не всегда критическая неисправность, а иногда просто неверно выбранный набор флагов.

Если ваша цель — восстановить файлы приложения, а не сделать максимально точную копию системного состояния, может хватить переноса содержимого и базовых времён модификации. Тогда лучше явно зафиксировать ожидаемое поведение, чем каждую ночь ловить rsync code 23 из-за несущественных атрибутов.

Проверяйте, от какого пользователя реально идёт запуск:

id
ps -o user= -p $$

Если задача работает из cron или systemd, полезно сверить пользователя юнита и окружение. Это классическая ловушка: ручной запуск от root проходит, а автоматический от служебного пользователя — нет.

Symlinks: когда всё выглядит нормально, но rsync всё равно ругается

Вторая большая категория — symlinks. Здесь нужно сразу определиться, что именно вы хотите копировать: сами симлинки как объекты файловой системы или файлы, на которые они указывают. От этого зависит и поведение, и набор ошибок.

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

Найти битые ссылки в источнике можно заранее:

find /src -xtype l -ls

Посмотреть, куда указывает конкретная ссылка:

readlink /src/path/link
readlink -f /src/path/link

Здесь важна тонкость: readlink -f пытается разыменовать путь до конечного объекта. Если цель отсутствует, вы быстро увидите broken symlink или исчезнувший target.

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

Если в выводе встречается symlink has no referent, почти всегда стоит отдельно инвентаризировать битые ссылки. Особенно это актуально для релизных каталогов, папок current, releases, пользовательских загрузок и старых деплоев.

find /src -type l | wc -l
find /src -xtype l | wc -l

Если симлинков много, заранее определите политику:

• копировать ссылки как ссылки;
• разыменовывать ссылки и копировать реальное содержимое;
• исключать отдельные проблемные пути;
• перед бэкапом валидировать дерево на битые ссылки.

Это не косметика, а часть надёжного backup-процесса.

Облачный VDS-сервер в России

Аренда виртуальных серверов с моментальным развертыванием инфраструктуры от 195₽ / мес

Подробнее

Vanished files: нормальная гонка, а не всегда поломка

Третья очень частая причина partial transfer — vanished files. Сообщение обычно выглядит так:

file has vanished: "/src/path/to/file"

Это значит, что во время сканирования файл существовал, а к моменту чтения уже исчез. То есть rsync увидел его в списке, но не успел скопировать. Обычно это связано с изменяющимся источником: ротацией логов, временными файлами приложения, очисткой кэша, CI/CD, контейнерами, очередями, загрузками пользователей или активной сборкой проекта.

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

Типовые кандидаты на исчезновение:

• логи в /var/log во время ротации;
• кэш приложений;
• временные каталоги tmp;
• сессии;
• артефакты сборки;
• динамические служебные файлы.

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

Для поиска самых «живых» зон дерева полезно посмотреть, какие файлы менялись недавно:

find /src -type f -mmin -5 | head

Или отследить события в каталоге во время прогона:

inotifywait -mr /src

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

Практический разбор вывода rsync по типам ошибок

Полезно научиться классифицировать сообщения с первого взгляда.

Ошибки чтения источника

rsync: [sender] send_files failed to open "/src/secret.txt": Permission denied (13)

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

Ошибки записи на приёмник

rsync: [receiver] mkstemp "/backup/file.XXXXXX" failed: Permission denied (13)

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

Ошибки metadata

rsync: [receiver] chgrp "/backup/file" failed: Operation not permitted (1)

Содержимое могло скопироваться, но не применились группа, владелец, права или время.

Битые ссылки

symlink has no referent: "/src/current"

Симлинк существует, а его цель отсутствует или недоступна.

Исчезнувшие файлы

file has vanished: "/src/cache/tmp12345"

Файл попал в список, но исчез до копирования.

Минимальный набор проверок перед исправлением команды

Прежде чем менять флаги вслепую, полезно пройти короткий чек-лист:

1. Понять, кто запускает rsync и какие у него права.
2. Определить, критичны ли пути, на которых возникает ошибка.
3. Проверить проблемные каталоги через namei -l и stat.
4. Выявить битые симлинки через find -xtype l.
5. Понять, какие файлы исчезают по ходу работы и почему.
6. Убедиться, что вы осознанно сохраняете ownership, ACL и xattrs.

После этого решение обычно становится очевиднее: где-то нужно запускать задачу от root, где-то исключить мусорные каталоги, где-то исправить структуру симлинков, а где-то отказаться от бэкапа живых данных без снапшота. Если речь идёт о базах данных, не стоит копировать их файлы вслепую: для PostgreSQL и MySQL корректнее использовать специализированные схемы вроде PITR с WAL для PostgreSQL.

Как безопасно локализовать проблемные файлы

Если дерево большое и логов много, задача — быстро получить список всех проблемных объектов.

Во-первых, используйте тестовый запуск в лог:

rsync -avHAX --numeric-ids --itemize-changes /src/ /backup/ > /tmp/rsync.log 2>&1

Во-вторых, выделяйте только строки ошибок:

grep '^rsync:' /tmp/rsync.log | sort | uniq

В-третьих, отдельно извлекайте vanished-файлы:

grep 'vanished' /tmp/rsync.log

И отдельно permission-проблемы:

grep 'Permission denied' /tmp/rsync.log

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

rsync -av /src/app/ /backup/app/
rsync -av /src/data/ /backup/data/
rsync -av /src/logs/ /backup/logs/

Виртуальный хостинг для сайтов

Универсальное решение для создания и размещения сайтов любой сложности в Интернете от 95₽ / мес

Подробнее

Когда менять флаги rsync, а когда — сам процесс бэкапа

Не все проблемы решаются параметрами rsync. Это важный практический вывод.

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

• если ошибка воспроизводится на одних и тех же путях, это обычно права, ownership или сломанная структура;
• если проблемные файлы каждый раз разные, чаще всего это изменяющийся источник и vanished files;
• если ошибки касаются только metadata, надо пересмотреть набор сохраняемых атрибутов;
• если ошибки только на целевой стороне, проверяйте права записи, mount options и особенности файловой системы приёмника.

Практические рекомендации для стабильного Linux backup

• Не бэкапьте всё подряд одним проходом. Разделяйте системные данные, пользовательские файлы, кэш и временные каталоги.
• Явно исключайте то, что не нужно для восстановления: кэши, временные файлы, сессии, мусор сборки.
• Проверяйте битые симлинки до запуска резервной копии.
• Если важно сохранить file ownership, ACL и xattrs, запускайте задачу с подходящими правами.
• Для активных данных используйте снапшоты или консистентные точки, а не копирование на лету.
• Храните полный лог и анализируйте именно первичные сообщения, а не только exit code.

Короткий runbook: что делать при rsync code 23

1. Перезапустить задачу вручную с подробным выводом в лог.
2. Посмотреть все строки rsync: до финального сообщения.
3. Отделить Permission denied от vanished files и проблем с symlinks.
4. Проверить проблемные пути через namei -l, stat, readlink.
5. Для нестабильных файлов понять, можно ли их исключить.
6. Для ownership и metadata решить, действительно ли их нужно сохранять.
7. После исправления сделать повторный прогон и убедиться, что код возврата стал 0.

Главная мысль простая: rsync code 23 — это не диагноз, а индикатор. Реальная причина почти всегда прячется в конкретных строках про permissions, symlinks, vanished files и file ownership. Как только вы начинаете разбирать эти сценарии по отдельности, ошибка перестаёт быть загадкой и превращается в обычную рабочую задачу.