From e3e2e0a2db18b5aab0572c8d377d60a0d8dccc66 Mon Sep 17 00:00:00 2001 From: r00t Date: Sun, 18 Dec 2016 02:55:40 -0500 Subject: [PATCH] updating docs; minor tweaks in bGPG and ipxe. --- bdisk/bGPG.py | 1 + bdisk/ipxe.py | 3 +- docs/manual/BODY.adoc | 4 +-- docs/manual/BOOT.adoc | 8 +++++ docs/manual/FAQ.adoc | 2 ++ docs/manual/HEAD.adoc | 3 +- docs/manual/boot/HOWTO.adoc | 39 ++++++++++++++++++++++++ docs/manual/faq/INDEX.adoc | 2 ++ docs/manual/faq/WHYARCH.adoc | 2 ++ docs/manual/user/IMPORTANT_CONCEPTS.adoc | 3 +- extra/dist.build.ini | 10 +++--- 11 files changed, 66 insertions(+), 11 deletions(-) create mode 100644 docs/manual/BOOT.adoc create mode 100644 docs/manual/boot/HOWTO.adoc diff --git a/bdisk/bGPG.py b/bdisk/bGPG.py index 3f9508e..f717d9f 100755 --- a/bdisk/bGPG.py +++ b/bdisk/bGPG.py @@ -16,6 +16,7 @@ def genGPG(conf): templates_dir = '{0}/extra/templates'.format(build['basedir']) mykey = False pkeys = [] + killStaleAgent(conf) if conf['gpg']['mygpgkey'] != '': mykey = conf['gpg']['mygpgkey'] if gpghome == '': diff --git a/bdisk/ipxe.py b/bdisk/ipxe.py index a09d874..aeed10a 100755 --- a/bdisk/ipxe.py +++ b/bdisk/ipxe.py @@ -271,8 +271,7 @@ def genISO(conf): '-output', isopath, bootdir] DEVNULL = open(os.devnull, 'w') - #subprocess.call(cmd, stdout = DEVNULL, stderr = subprocess.STDOUT) - subprocess.call(cmd) + subprocess.call(cmd, stdout = DEVNULL, stderr = subprocess.STDOUT) # Get size of ISO iso['name'] = ['Mini'] iso['Mini'] = {} diff --git a/docs/manual/BODY.adoc b/docs/manual/BODY.adoc index 97770f3..a4b48f6 100644 --- a/docs/manual/BODY.adoc +++ b/docs/manual/BODY.adoc @@ -1,5 +1,5 @@ include::USER.adoc[] include::DEV.adoc[] include::FAQ.adoc[] - -include::FOOT.adoc[] \ No newline at end of file +include::BOOT.adoc[] +include::FOOT.adoc[] diff --git a/docs/manual/BOOT.adoc b/docs/manual/BOOT.adoc new file mode 100644 index 0000000..756a0af --- /dev/null +++ b/docs/manual/BOOT.adoc @@ -0,0 +1,8 @@ += Netboot +[partintro] +.What good is software if you can't see it in action? +-- +It's possible to netboot my personal build of BDisk. I mostly keep this up for emergencies in case I need it, but it's good to show you that yes, you can boot a 2GB+ squashed and compressed filesystem from a <50MB image file. +-- + +include::boot/HOWTO.adoc[] diff --git a/docs/manual/FAQ.adoc b/docs/manual/FAQ.adoc index 154421d..7c12101 100644 --- a/docs/manual/FAQ.adoc +++ b/docs/manual/FAQ.adoc @@ -7,3 +7,5 @@ Here you will find some answers to Frequently Asked Questions I've received abou -- include::faq/INDEX.adoc[] + + diff --git a/docs/manual/HEAD.adoc b/docs/manual/HEAD.adoc index 7e936c5..aee12f5 100644 --- a/docs/manual/HEAD.adoc +++ b/docs/manual/HEAD.adoc @@ -4,6 +4,7 @@ v1.0, 2016-12 :doctype: book :data-uri: :imagesdir: images +:sectlinks: :toc: preamble :toc2: left :sectnums: @@ -27,7 +28,7 @@ A lot of research went into how low-level boot operations take place when writin === What is BDisk? BDisk refers to both a live distribution I use in my own uses (for rescue situations, recovery, etc.) but foremost and most importantly, it also refers to the tool I use for building that distribution. The latter is what this project and documentation refer to when the word “BDisk” is used. -When I rewrote BDisk in Python 3.x (I should take the time to note that I am still quite new to Python so expect there to be plenty of optimizations to be made and general WTF-ery from seasoned Python developers), one of my main goals was to make it as easy to use as possible. This is surprisingly hard to do- it’s quite challenging to try to approach software you’ve written with the mindset of someone other than you. +When I rewrote BDisk in Python 3.x (Version 0.x-2.x of BDisk was written in Bash, and horribly inelegant and rigid. I should take the time to note that I am still quite new to Python so expect there to be plenty of optimizations to be made and general WTF-ery from seasoned Python developers), one of my main goals was to make it as easy to use as possible. This is surprisingly hard to do- it’s quite challenging to try to approach software you’ve written with the mindset of someone other than you. 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!). diff --git a/docs/manual/boot/HOWTO.adoc b/docs/manual/boot/HOWTO.adoc new file mode 100644 index 0000000..557f34d --- /dev/null +++ b/docs/manual/boot/HOWTO.adoc @@ -0,0 +1,39 @@ +== How to Netboot BDisk +I update this server with images and iPXE images you can use to netboot my personal spin of BDisk. + +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]). My key can be found in https://square-r00t.net/gpg/ascii/personal.asc[ASC] or https://square-r00t.net/gpg/bin/personal.gpg[BIN] format. Proofs of identity can be found in the footnotes of https://devblog.square-r00t.net/articles/a-note-on-using-gpg-signatures-in-pkgbuilds[this] blog post. 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: + +=== Windows +==== CD/DVD +Simply put a blank CD/DVD-R (or RW, RW+, etc.) in your optical media drive. Find where you downloaded the above file (it should be named `bdisk-mini.iso`). Right-click and select *Burn disc image*. + +==== USB +You'll most likely want to https://svwh.dl.sourceforge.net/project/usbwriter/USBWriter-1.3.zip[download] a program caled https://sourceforge.net/projects/usbwriter/[USBWriter]. Unzip it (or just open it via double-clicking) and copy the USBWriter.exe program somewhere you'll remember- your desktop, for instance. + +Next, make sure your USB stick is inserted in your computer and https://support.microsoft.com/en-us/help/17418/windows-7-create-format-hard-disk-partition[formatted/"initialized"] already. + +CAUTION: Formatting a disk/partition will *destroy* any and all data on that device! Make sure there is nothing on your USB drive you want to keep, as formatting BDisk to it *will* delete any data on it. + +Now right-click on the USBWriter icon and select *Run as administrator*. You may get a warning pop up asking for permissions for USBWriter. It's safe to click Yes. + +Select the proper USB flash drive from the *Target device* dropdown menu. If your USB drive isn't showing up, try clicking the Refresh button and looking again. (If it still doesn't show up, you may need to reboot your computer.) + +Click the *Browse...* button and find where you saved `bdisk-mini.iso`. Once you've found it, double-click it. Then click *Write*. It might take a little bit of time depending on how fast your USB interface is, so give it some time. When it finishes, click *Close*. You now have a bootable USB thumbdrive. + +==== Booting +Booting differs depending on each and every hardware, but *typically* you should get a message when you first start up for "_Setup_" and/or "_Boot options_" or the like. The terminology differs here. It will probably be an *F__#__* button (usually `F2`, `F4`, `F10`, or `F12`) or the *Delete* key. While rebooting, try to hold or press repeatedly this key and you should come across an option somewhere with a list of devices to boot from or an order you can set. Make sure the USB (or CD/DVD, whichever media type you're using) is set as first, and save. + +=== Mac OS X/macOS +==== CD/DVD +==== USB +==== Booting +The instructions here don't differ too much than from Windows, though it's always the same key. For OS X/macOS hardware, I believe it's the *c* key or the *b* key. From it being in a shutdown state, power on your Macbook Pro (or whatever it is you have) and hold the *c* key if it's CD/DVD. The *b* key should bring up a boot menu that will let you select a USB device to boot from. + +=== GNU/Linux +==== CD/DVD +==== USB +==== Booting diff --git a/docs/manual/faq/INDEX.adoc b/docs/manual/faq/INDEX.adoc index 6124f52..2d9ccec 100644 --- a/docs/manual/faq/INDEX.adoc +++ b/docs/manual/faq/INDEX.adoc @@ -1 +1,3 @@ include::WHYARCH.adoc[] + + diff --git a/docs/manual/faq/WHYARCH.adoc b/docs/manual/faq/WHYARCH.adoc index 02eb81d..334aa7f 100644 --- a/docs/manual/faq/WHYARCH.adoc +++ b/docs/manual/faq/WHYARCH.adoc @@ -3,3 +3,5 @@ Because it's a very easy-to-use, simple, https://wiki.archlinux.org/[well-docume Plus they have tarballs all ready for chroot easily accessible. + + diff --git a/docs/manual/user/IMPORTANT_CONCEPTS.adoc b/docs/manual/user/IMPORTANT_CONCEPTS.adoc index 49fc5e8..ea88c9a 100644 --- a/docs/manual/user/IMPORTANT_CONCEPTS.adoc +++ b/docs/manual/user/IMPORTANT_CONCEPTS.adoc @@ -9,4 +9,5 @@ There are two basic types of booting systems that communicate between the *hardw *GNU/Linux*, sometimes just referred to as _Linux_ (And there is a difference between the terminologies, but it's nuanced. You are welcome to https://www.gnu.org/gnu/linux-and-gnu.en.html[read up on it] though!), is an example of an operating system. Other examples include _Windows_, _macOS_ (previously _OS X_), _iOS_, _Android_, and a whole slew of others. -A *live distro*, *live CD*, *live DVD*, *live USB*, and the like are a way of booting an operating system without installing it on the hard drive- this means the computer doesn't even need a hard drive installed, or it doesn't matter if the operating system is broken. Typically they are Linux-based, but there are several Windows-based live releases out there (usually they're focused on rescuing broken systems, so they're not very useful). +A *live distro*, *live CD*, *live DVD*, *live USB*, and the like are a way of booting an operating system without installing it on the hard drive- this means the computer doesn't even need a hard drive installed, or it doesn't matter if the operating system is broken. Typically they are Linux-based, but there are several Windows-based live releases out there (usually they're focused on rescuing broken Windows systems, so they're not very flexible). + diff --git a/extra/dist.build.ini b/extra/dist.build.ini index 280e4ac..a593458 100644 --- a/extra/dist.build.ini +++ b/extra/dist.build.ini @@ -183,7 +183,7 @@ mirrorchksum = ${mirrorpath}sha1sums.txt ; ${mirrorproto}://${mirror}${mirrorpath}somefile.sig) ; 0.) No whitespace (if specified) ; 1.) Must be the full path -mirrorgpgsig = ${mirrorfile}.sig +mirrorgpgsig = ; What is a valid key ID that should be used to ; verify the tarballs? @@ -208,7 +208,7 @@ gpgkeyserver = ; yes|no ; true|false ; 1|0 -gpg = yes +gpg = no ; Where should we save the bootstrap tarballs? ; 0.) No whitespace @@ -332,7 +332,7 @@ mygpghome = ; true|false ; 1|0 ; If it is undefined, it is assumed to be no. -http = yes +http = no ; Should we generate/prepare TFTP files? ; This is mostly only useful if you plan on using more @@ -343,7 +343,7 @@ http = yes ; true|false ; 1|0 ; If it is undefined, it is assumed to be no. -tftp = yes +tftp = no ; Enable automatic Git pushing for any changes done to the ; project itself? If you don't have upstream write access, @@ -426,7 +426,7 @@ group = root ; 1|0 ; 1.) Requires actual git to be installed. ; If it is undefined, it is assumed to be no. -iso = yes +iso = no ; What URI should iPXE's EMBED script use? ; If you require HTTP BASIC Authentication or HTTP Digest