documentation checkin
This commit is contained in:
parent
d0d8105db3
commit
0c9dcfd833
@ -33,6 +33,8 @@ This documentation was started when I rewrote BDisk in Python 3.x; versions 0.x-
|
||||
|
||||
It’s my hope that by releasing this utility (and documenting it), you can use it and save some time for yourself as well (and hopefully get the chance to learn a bit more in the process!).
|
||||
|
||||
It of course is not the <<i_don_t_like_bdisk_are_there_any_other_alternatives,only live media creator>> out there, but most others only focus on remastering an existing ISO, or creating an installer ISO -- not creating a custom live-centric environment.
|
||||
|
||||
|
||||
=== Copyright/Licensing
|
||||
The BDisk code is https://www.gnu.org/licenses/gpl-3.0.en.html[GPLv3-licensed^]. This means that you can use it for business reasons, personal reasons, modify it, etc. Please be sure to familiarize yourself with the full set of terms. You can find the full license in `docs/LICENSE`.
|
||||
|
||||
@ -22,4 +22,5 @@ include::user/IMPORTANT_CONCEPTS.adoc[]
|
||||
include::user/PROJECT_LAYOUT.adoc[]
|
||||
include::user/BUILDINI.adoc[]
|
||||
include::user/ADVANCED.adoc[]
|
||||
include::user/BUILDING.adoc[]
|
||||
|
||||
|
||||
@ -46,31 +46,38 @@ Written in Bash.
|
||||
|======================
|
||||
|
||||
=== Debian's https://wiki.debian.org/Simple-CDD[Simple-CDD^]
|
||||
Written in Bash.
|
||||
(TODO)
|
||||
Written in Bash (some Python).
|
||||
[frame="topbot",options="header,footer"]
|
||||
|======================
|
||||
|Pros|Cons
|
||||
||
|
||||
|Supports custom packages to be installed|Very limited -- no customization beyond package listing
|
||||
|Lightweight; quick to set up|Takes a long time for preparation; requires a clone of many .deb packages first.
|
||||
||Doesn't seem to work as according to https://wiki.debian.org/Simple-CDD/Howto[the documentation^]
|
||||
||Documentation is sparse
|
||||
||Full featureset unknown due to ISO not building on Debian Jessie (8.0)
|
||||
||
|
||||
|======================
|
||||
|
||||
=== Fedora's https://fedoraproject.org/wiki/Livemedia-creator-_How_to_create_and_use_a_Live_CD[Livemedia-creator^]
|
||||
Written in Bash.
|
||||
(TODO)
|
||||
[frame="topbot",options="header,footer"]
|
||||
|======================
|
||||
|Pros|Cons
|
||||
||
|
||||
|Somewhat customizable|Requires manual initialization of chroot(s) via https://github.com/rpm-software-management/mock/wiki[mock^]
|
||||
|Uses kickstart configurations|*Requires* a kickstart configuration to be useful
|
||||
|Simple/easy to use|Full featureset unknown; documentation is sparse
|
||||
||Limited configuration/customization
|
||||
||
|
||||
|======================
|
||||
|
||||
=== https://github.com/rhinstaller/livecd-tools[LiveCD Tools^]
|
||||
Written in Bash.
|
||||
Written in Python 2, some Bash.
|
||||
[frame="topbot",options="header,footer"]
|
||||
|======================
|
||||
|Pros|Cons
|
||||
||
|
||||
|Can use kickstarts|*Requires* a kickstart configuration
|
||||
|Simple/easy to use to use|Limited configuration/customization
|
||||
|Automatically builds chroots|Full featureset unknown; documentation is sparse
|
||||
||
|
||||
|======================
|
||||
|
||||
|
||||
3
docs/manual/faq/GETVERSION.adoc
Normal file
3
docs/manual/faq/GETVERSION.adoc
Normal file
@ -0,0 +1,3 @@
|
||||
== How do I get the version/build of an ISO?
|
||||
This can be found in a multitude of places. The full-size ISO file (iso/<distname>-<git tag>-<git rev number>-(32|64|any).iso) should have the version right in the filename. If you want more detailed information (or perhaps you renamed the file), you can mount the ISO as loopback in GNU/Linux, *BSD, or Mac OS X/macOS and check `/path/to/mounted/iso/VERSION_INTO.txt`. Lastly, within the runtime itself (especially handy if booting via iPXE), you can check `/root/VERSION_INFO.txt` to get information about the build of the currently running live environment.
|
||||
|
||||
@ -1,2 +1,5 @@
|
||||
include::WHYARCH.adoc[]
|
||||
include::LONGTIME.adoc[]
|
||||
include::ISOBIG.adoc[]
|
||||
include::GETVERSION.adoc[]
|
||||
include::ALTERNATIVES.adoc[]
|
||||
|
||||
5
docs/manual/faq/ISOBIG.adoc
Normal file
5
docs/manual/faq/ISOBIG.adoc
Normal file
@ -0,0 +1,5 @@
|
||||
== Why is the ISO so large?
|
||||
This actually entirely depends on what <<changing_the_installed_software,packages you have chosen to install>> (and if you're building a <<code_multiarch_code,multiarch ISO>>). The default list is quite large.
|
||||
|
||||
If you build a minimal ISO (i.e. only the necessary components required for booting and nothing else, single-arch), the ISO is only about 570MB (but work is being done to make this even smaller).
|
||||
|
||||
94
docs/manual/faq/LONGTIME.adoc
Normal file
94
docs/manual/faq/LONGTIME.adoc
Normal file
@ -0,0 +1,94 @@
|
||||
== Why does building take so long?
|
||||
This typically occurs when you're building from within a LiveCD/LiveUSB situation, in a VM/container/etc., or on a headless server. If this is the case, you may run into what appears to be "stalling", especially while keys are generating for the chroots. Thankfully, there is an easy fix. You can install http://www.issihosts.com/haveged/[haveged^] and run it (this can be done safely while a build is executing). This will show an immediate and non-negligible improvement for the above contexts. If you have extra processing power to throw at the build process (or are using a dedicated build box) as well, I recommend enabling <<code_i_am_a_racecar_code,`i_am_a_racecar`>>. BDisk will then be more aggressive with its resource consumption.
|
||||
|
||||
=== Running a local mirror
|
||||
Keep in mind also that the more packages you opt to install, the longer the build process will take. This process will also use quite a fair bit of bandwidth. If you plan on building regular images (e.g. nightly builds, etc.) or are undergoing some custom change testing, I recommend running a private repository mirror on-site. This will not store AUR packages, as those will still be fetched and built (documentation on working around this is TODO) but setting up a local mirror is quite quick and easy.
|
||||
|
||||
First, you'll need at least 70Gb of free disk space. Let's say our repository clone will be at `/srv/repo/arch/`.
|
||||
|
||||
You'll also need to find an Arch mirror, ideally one close to you that is up-to-date. The https://www.archlinux.org/mirrorlist/[mirrorlist generator^] and https://www.archlinux.org/mirrors/[mirror list^] will assist you here greatly.
|
||||
|
||||
NOTE: You'll need to find a mirror that supports _rsync_.
|
||||
|
||||
TIP: You can use ANY distro to run a repository mirror, as long as it has _rsync_ installed!
|
||||
|
||||
==== Set up the sync
|
||||
|
||||
Create a script and mark it as executable with the following content:
|
||||
|
||||
#!/bin/bash
|
||||
SOURCE='rsync://your.mirror.here/archlinux'
|
||||
DEST='/srv/repo/arch'
|
||||
LCK_FLE='/var/run/repo-sync.lck'
|
||||
PATH='/usr/bin'
|
||||
if [ -e "${LCK_FLE}" ] ; then
|
||||
OTHER_PID=$(cat ${LCK_FLE})
|
||||
echo "Another instance already running: ${OTHER_PID}"
|
||||
exit 1
|
||||
fi
|
||||
# If e.g. /srv/repo is a mountpoint, uncomment below.
|
||||
#findmnt /srv/repo > /dev/null 2>&1
|
||||
#if [[ "${?}" -ne '0' ]];
|
||||
#then
|
||||
# echo "External storage not mounted!"
|
||||
# exit 1
|
||||
#fi
|
||||
echo $$ > "${LCK_FLE}"
|
||||
rsync -rvtlH --delete-after --delay-updates --safe-links --max-delete=1000 ${SOURCE}/. ${DEST}/. >> /var/log/arch.repo.sync 2>&1
|
||||
date +%s > ${DEST}/lastsync
|
||||
rm -f "${LCK_FLE}"
|
||||
|
||||
Assuming you want to run the sync script every 6 hours and it is located at `/root/bin/arch.repo.clone.sh`, this is the cron entry you would use (`crontab -e`):
|
||||
|
||||
0 */6 * * * /root/bin/arch.repo.clone.sh > /dev/null 2>&1
|
||||
|
||||
The first sync can take quite a while, but subsequent runs shouldn't take more than five minutes or so.
|
||||
|
||||
==== Configuring the local mirror
|
||||
You'll need a way to serve this local mirror in a way pacman can understand. Luckily, it's fairly easy. I recommend using https://www.nginx.com/[nginx^] as it's available by default in many operating systems. You can of course use others such as https://www.lighttpd.net/[lighttpd^], https://httpd.apache.org/[apache/httpd^], etc. For the example configuration here, we're going to use an nginx configuration file.
|
||||
|
||||
```
|
||||
server {
|
||||
listen [::]:80;
|
||||
access_log /var/log/nginx/repo.access.log main;
|
||||
error_log /var/log/nginx/repo.error.log;
|
||||
#error_log /var/log/nginx/repo.error.log debug;
|
||||
|
||||
autoindex on;
|
||||
|
||||
root /srv/repo/arch;
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
The configuration may vary according to your distribution's provided nginx default configuration, but you'll want this configuration to be served as the default (or set an appropriate `https://nginx.org/en/docs/http/server_names.html[server_name]` directive which you would then use in `<basedir>/extra/pre-build.d/etc/pacman.d/mirrorlist`).
|
||||
|
||||
==== Configuring BDisk
|
||||
|
||||
You'll then want to configure BDisk's chroots to use your local mirror first. However, when doing so you run into an issue -- in the built image, install operations will take longer than they need to because the local mirror likely won't be available! This is a small issue as it's unexpected that you'll need to install software within the live environment, but I've run into cases where it was a necessity once or twice.
|
||||
|
||||
There is an https://devblog.square-r00t.net/articles/libvirt-spoof-domains-dns-records-redirect-to-another-ip[easy workaround^] if you're using libvirt -- you can simply tell your build VM to resolve to the IP address of the box that is running the mirror for the same FQDN that the "preferred" "real" mirror on the Internet is and set that mirror at the top of `<basedir>/extra/pre-build.d/etc/pacman.d/mirrorlist`. However, that's not always feasible- most notably if you're building on a physical box and it's the same host as the repository clone. In that case you can set the specific local resolution -- e.g. `http://127.0.0.1/` -- at the top of `<basedir>/extra/pre-build.d/etc/pacman.d/mirrorlist` and then set a mirrorlist WITHOUT that entry in `<basedir>/overlay/etc/pacman.d/mirrorlist`. For more information on using these type of overrides, see <<advanced_customization>>.
|
||||
|
||||
If you're using the libvirt workaround, remember to configure nginx (or whatever you're using) with a virtual host and location block that matches the "real", upstream mirror. In our example below, we use *http://mirror.us.leaseweb.net/archlinux* as the mirror.
|
||||
|
||||
```
|
||||
server {
|
||||
listen [::]:80;
|
||||
access_log /var/log/nginx/repo.access.log main;
|
||||
error_log /var/log/nginx/repo.error.log;
|
||||
#error_log /var/log/nginx/repo.error.log debug;
|
||||
|
||||
server_name mirror.us.leaseweb.net;
|
||||
|
||||
autoindex on;
|
||||
|
||||
root /srv/repo/arch;
|
||||
|
||||
location /archlinux {
|
||||
autoindex on;
|
||||
rewrite ^/archlinux(/.*)$ /$1;
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
@ -3,7 +3,7 @@ I update this server with images and iPXE images you can use to netboot my perso
|
||||
|
||||
You can https://bdisk.square-r00t.net/download/bdisk-mini.iso[download] a demo of the iPXE functionality. Note that your computer needs to be connected to a valid Internet connection via ethernet and be able to get a DHCP lease for it to work.
|
||||
|
||||
NOTE: Advanced users, you can https://www.gnupg.org/gph/en/manual/x135.html[verify^] it against the GPG signature (https://bdisk.square-r00t.net/download/bdisk-mini.iso.asc[ASC], https://bdisk.square-r00t.net/download/bdisk-mini.iso.gpg[BIN]). Please see https://devblog.square-r00t.net/about/my-gpg-public-key-verification-of-identity[this blog post^] for information on fetching my keys and such. Note that while this project is in flux, I may be signing with temporarily-generated throwaway keys.
|
||||
NOTE: Advanced users, you can https://www.gnupg.org/gph/en/manual/x135.html[verify^] it against the GPG signature (https://bdisk.square-r00t.net/download/bdisk-mini.iso.asc[ASC], https://bdisk.square-r00t.net/download/bdisk-mini.iso.sig[BIN]). Please see https://devblog.square-r00t.net/about/my-gpg-public-key-verification-of-identity[this blog post^] for information on fetching my keys and such. Note that while this project is in flux, I may be signing with temporarily-generated throwaway keys.
|
||||
|
||||
Once downloaded, you can follow the appropriate steps based on your operating system:
|
||||
|
||||
|
||||
13
docs/manual/user/BUILDING.adoc
Normal file
13
docs/manual/user/BUILDING.adoc
Normal file
@ -0,0 +1,13 @@
|
||||
== Building a BDisk ISO
|
||||
So you finally have <<the_code_build_ini_code_file,configured>> BDisk (and perhaps added further <<advanced_customization,customizations>>. Now you're ready to build!
|
||||
|
||||
Building is, thankfully, the easiest part!
|
||||
|
||||
NOTE: Due to requiring various mounting and chrooting, BDisk must be run as the *root* user (or via _sudo_).
|
||||
|
||||
To initiate a build, simply run `<basedir>/bdisk/bdisk.py`. That's it! Everything should continue automatically.
|
||||
|
||||
If you're using a packaged version you installed from your distro's package manager, you instead should run wherever it installs to. Most likely this is going to be `/usr/sbin/bdisk`. (On systemd build hosts that have done the https://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge/[/usr merge^], you can use `/usr/sbin/bdisk` or `/sbin/bdisk`.)
|
||||
|
||||
If you encounter any issues during the process, make sure you read the documentation -- if your issue still isn't addressed, please be sure to file a <<bug_reports_feature_requests,bug report>>!
|
||||
|
||||
Loading…
Reference in New Issue
Block a user