FreeBSD virtual environment management and repository

Внимание! Данные страницы описывают CBSD версии 12.1.x. Если вы используете более раннюю версию, рекомендуется сначала обновиться.

fetch

Описание

При работе CBSD может возникнуть потребность загрузить какие-либо дополнительные ресурсы из интернет. Это может быть, например: базовые FreeBSD файлы для построения клетки, ISO образы той или иной ОС которую вы хотите установить, различные темплейты и сервисные образы виртуальных машин.

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

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

CRC суммы также сопровождают участники CBSD проекта и берутся из официальных источников (сайт-производитель ОС, официальный сайт FreeBSD и т.д.).

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

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

fetch.conf

Конфигурационные файлы CBSD, содержащие ссылки на внешние ресурсы (например шаблоны bhyve виртуальных машин, расположенные в каталоге $workdir/etc/defaults/ и начинающиеся с vm-*, делятся на два вида:

  • iso_site - официальный сайт или официальное зеркало проекта, первоисточник данных. Именно с этих ресурсов подсчитывается CRC сумма файлов.
  • cbsd_iso_mirrors - официальное зеркало проекта CBSD. Эти зеркала учавствуют при получении файлов, но никогда не используются как первоисточник CRC сумм, поскольку они могут быть расположены на пользовательских или партнерских ресурсах. Обеспечение целостности с этих зеркал гарантируется проверкой SHA256 суммы, созданной по оригинальному файлу.

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

Бывают случаи, когда файл, указанный в конфигурационном файле, изменяется на официальном ресурсе и по этой причине он не проходит проверку. В этом случае доступны два алгоритма поведения, регулируемые через параметр broken_crc_fetch_order в конфигурационном файле fetch.conf:

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

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

По-умолчанию, выбран метод broken_crc_fetch_order="mirror_list", однако, если вы предпочитаете изменить поведение на первый вариант, перезапишите эту настройку, создав файл в $workdir/etc/fetch.conf и переназначьте в нем параметр:

 broken_crc_fetch_order="cbsd_mirror" 

Возможно, эта настройка поможет сэкономить трафик, если по рейтингу скорости зеркала CBSD оказались в конце списка.

Если вы заметили некорректную CRC сумму, вы можете помочь проекту и отправить обновление профиля и CRC суммы, о чем сказано ниже.

Если CRC не совпадает

В момент релиза CBSD, все профили проходят проверку и содержат корректные CRC суммы, однако, с течением времени эта ситуация может измениться - например, авторы ОС выпустили обновление образа на своем ресурсе.

В таких случаях, попытка получения образа с официального сайта (и его зеркал) будет заканчиваться ошибкой CRC суммы, тогда как официальные зеркала CBSD проекта будут отдавать правильную, но старую копию.

В таких случаях необходимо обновить контрольные суммы в профилях и обновить образ.

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

Чтобы сделать это, вы должны иметь установленным в вашу систему утилиту git. Обновление происходит через Makefile сценарий в каталое $workdir/etc. Чтобы выполнить обновление:

 make -C ~cbsd/etc profiles-update

Вы можете добавить эту операцию в crontab для автоматического периодического обновления. Если вы делаете это первый раз, перед profiles-update необходимо провести инициализацию git репозитория (делается только один раз):

 make -C ~cbsd/etc profiles-create

Если обновлений нет, вы можете помочь проекту (и осчастливить тем самым таких же пользователей как и вы), создав через GitHub соответствующий pull-request для изменения CRC суммы (или обновления ссылок и версии).

Если вы на свой страх и риск хотите принять ISO образ не смотря на несовпадение CRC сумм, для вас есть два варианта:

  • Отрегулировать значение sha256sum в конкретном профиле через установку sha256sum=0. Когда sha256sum=0, это заставляет CBSD пропускать проверку CRC. Обратитесь в раздел Профили CBSD для подробной информации о том, как перезаписать те или иные параметры.
  • Запретить проверку CRC сумм глобально через переменную окружения BSD_ISO_SKIP_CHECKSUM=[yes|no] (или конфигурационный файл), например: env CBSD_ISO_SKIP_CHECKSUM=yes cbsd bstart ..

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

Партнерская программа, или "Разворачиваем зеркало ресурсов CBSD"

Для облегчения задач по работе с CRC суммами написан скрипт fetch_iso. Скрипт решает две основных задачи:

  • Автоматически обновить sha256 суммы в профилях путем скачивания ISO образа (только с официальных ресурсов, iso_site) и переподсчетом sha256, после чего CRC обновляется в файле /usr/local/cbsd/etc/defaults/vm-*. Для того, чтобы он вступил в силу, необходимо выполнить cbsd initenv. Кроме этого, этот файл можно отправить в качестве pull-request через GitHub. Для этого, используйте вызов fetch_iso с аргументом gensha256=1.
  • Помочь пользователям CBSD автоматизировать процесс построения собственного зеркала ресурсов, на которые ссылаются профили

В свою очередь, процесс построения собственного зеркала может делиться на два вида:

  • с аргументом keepname=1 - сохранить ISO под тем именем, как они названы на оригинальном (официальном) ресурсе. Этот вариант может использоваться, если вы хотите поднять собственное локальное зеркало CBSD ресурсов и использовать его как локальный (и конечно же - самый быстрый для вас из всех доступных) ресурс.
  • с аргументом keepname=0 - в этом случае, файлы сохранятся под теми именами, которые ожидают CBSD профили. Эта операция может выполняться в качестве "подогрева" образов, с целью скачать все ресурсы к себе заранее. Как правило, в качестве dstdir= выступает каталог /usr/jails/src/iso (если $workdir = /usr/jails), в котором CBSD хранит все ISO образы.

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

Также, для желающих помочь проекту с локальным зеркалом на ваших ресурсах, есть открытый в режиме RO сервер rsync, с которого через cron вы можете инициировать синхронизацию контента. Адрес этого ресурса: rsync://cbsd.lifec0re.net:30873. Если ваше зеркало доступно из интернет, вы можете послать pull-request на GitHub в репозиторий https://github.com/cbsd/cbsd-vmprofiles добавив ваше зеркало в параметре cbsd_iso_mirrors=. С выходом нового релиза CBSD, ваше зеркало войдет в CBSD.

Как поднять зеркало, HowTo

Step-by-step конфигурирования зеркала с периодической синхронизацией через rsync в crontab(5):

1) Установить пакеты:

			pkg install -y rsync nginx
		

2) Активировать сервис nginx:

		sysrc nginx_enable="YES"
		

3) Создать каталог /usr/local/www/cbsd-mirror куда будем сохранять образы, создадим лог файл для rsync и выставим корректные права для пользователя www, от которого мы будем синхронизировать

		mkdir -p /usr/local/www/cbsd-mirror/iso /usr/local/www/cbsd-mirror/cloud
		touch /var/log/cbsd_mirror.log /var/log/cbsd_mirror_cloud.log
		chown -R www:www /usr/local/www/cbsd-mirror /var/log/cbsd_mirror.log /var/log/cbsd_mirror_cloud.log
		

4) Откорректируем nginx.conf, указав в качестве server_name корректное имя сервера (в данном примере: electrode.bsdstore.ru) и путь к корневому каталогу:

		cat > /usr/local/etc/nginx/nginx.conf <<EOF
		user nobody;
		worker_processes  2;

		error_log /var/null;
		pid /var/run/nginx.pid;

		events {
			worker_connections  1024;
			kqueue_changes  1024;
			use kqueue;
		}

		http {
			server_tokens off;
			include       mime.types;
			default_type  application/octet-stream;

			log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
				'$status $body_bytes_sent "$http_referer" '
				'"$http_user_agent" "$http_x_forwarded_for"';

			error_log       /dev/null;
			access_log      /dev/null;
			client_header_timeout  3m;
			client_body_timeout    3m;
			send_timeout           3m;
			client_header_buffer_size    1k;
			large_client_header_buffers  4 8k;
			client_body_buffer_size 32K;
			log_not_found off;

			client_max_body_size 20m;

			gzip off;
			output_buffers   1 32k;
			postpone_output  1460;
			reset_timedout_connection  on;
			sendfile         on;
			tcp_nopush       on;
			tcp_nodelay      on;
			send_lowat       12000;
			keepalive_timeout  8;

			server {
				listen       *:80;
				#listen      [::]:80;	# Enable IPv6

				server_name  electrode.bsdstore.ru;
				access_log /var/log/nginx/electrode.bsdstore.ru.acc main;
				error_log /var/log/nginx/electrode.bsdstore.ru.err;

				root   /usr/local/www/cbsd-mirror;
			}
		}
		EOF
		

5) Создадим запись в Crontab с вызовом rsync в интервале 15 минут через lockf, чтобы пресечь дубляж процессов

		cat > /etc/cron.d/cbsd_mirror <<EOF
		SHELL=/bin/sh
		PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin
		*/15    *       *       *       *       www /usr/bin/lockf -s -t0 /tmp/cbsd_mirror.lock /usr/local/bin/rsync -a rsync://electro.bsdstore.ru/iso/ /usr/local/www/cbsd-mirror/iso/ > /var/log/cbsd_mirror.log 2>&1
		*/15    *       *       *       *       www /usr/bin/lockf -s -t0 /tmp/cbsd_mirror_cloud.lock /usr/local/bin/rsync -a rsync://electro.bsdstore.ru/cloud/ /usr/local/www/cbsd-mirror/cloud/ > /var/log/cbsd_mirror_cloud.log 2>&1
		EOF
		

6) Стартуем сервис

		service nginx restart
		

После синхронизации каталога и проверки, что ISO образы с вашего ресурса отдаются в мир - вы можете присылать Pull Request в профили проекта с добавленным в cbsd_iso_mirrors вашим сервером в профилях виртуальных машин.