FreeBSD virtual environment management and repository

2020-10 upd: we reached the first fundraising goal and rented a server in Hetzner for development! Thank you for donating !

Внимание! Данные страницы описывают CBSD версии 13.0.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 вашим сервером в профилях виртуальных машин.