Add Proper Documentation for Usage

[johnramsden]

Documentation should probably be added on how to use with both an all ZFS set up, and a regular setup. We should probably also describe our design decisions and why the strange partition layout is used.

• [x] Regular non boot on ZFS setup instructions
• [x] boot on ZFS setup instructions

So far I've added an example set up for Arch that I have confirmed boots. Other examples could probably be added, or the current example could be generalized.

Welcoming criticism and or documentation. Progress for the state of documentation could be followed in this branch and pull request until we have something working with an explanation on how it can be used.

Alternatively, a brief explanation of the project could be all that is in the readme, and we could use a Wiki for more detailed usage.

[danboid]

I'm not clear on the partitioning required to use zedenv-grub yet. The current guide starts by saying:

"One of two types of setup needs to be used with grub. On(sp) all ZFS setup, or a setup with kernels partition."

On the 2 machines on which I (sometimes) run ZoL, I run in BIOS/non-UEFI mode and because of this I only have to have 2 partitions on my disks- a small 2 MB non-fs partition at the start of the disk for the grub loader and then the rest of the disk is one ZFS partition, hence /boot is part of my only ZFS partition.

The quoted sentence above makes me think I should be able to retain this minimal partitioning scheme, hopefully that is the case but the existing instructions only seem to cover using a separate /boot partition or one of the two potential setups supported, unless I misread them? Please make it clearer what type of disk partitioning the code snippets apply to.

At the top are 3 bullet points, detailing various /boot configs but its unclear if these bullet points relate to 3 distinct config options or a single system.

In the "convert existing system" section it says "unmount /boot". Is this expecting a ext/xfs /boot or a ZFS /boot? Does the fs type or /boot partition size matter to zedenv, if the user has a /boot partition?

In your email to me you said:

"You also want to copy and make executable 'grub.d/40_zedenv_custom' to '/etc/grub.d/40_zedenv_custom'"

Why does the zedenv-grub installer not do this? Will it?

Once zedenv-grub is correctly installed, how is it used ie when/how do the grub entries for the BEs get updated? I would presume it does it every time zedenv create, activate or destroy is run?

The README should also mention running zedenv --plugins to check the grub plugin is installed properly.

[johnramsden]

So you are using an "All ZFS" setup then. It should work with that. It will generate config using this syntax:

menuentry 'Linux ...' { 
linux /ROOT/default/@/boot/vmlinuz-linux zfs=vault/ROOT/default rw 
initrd /ROOT/default/@/boot/initramfs-linux.img 
}

You're right regarding installing the grub.d script, i'll add that to setup.py,. It's actually the grub.d/10_zfs_linux.py file though, 40_zedenv_custom was the old shell script, sorry for the confusion.

Once installed, on activate, it generates entries.

I'll setup a BIOS root on ZFS VM later, and document the setup.

Thanks for the feedback.

[danboid]

My ALEZ install script currently only supports installing to a BIOS (non-UEFI) all-ZFS / GRUB config. You can set up such a config in no time using my script/ISO. I have remastered arch to include zfs and my script to make installation as quick and easy as possible. It's only of use if you are happy with a single or dual disk (mirrored) config currently.

I plan to add the ability to choose the lts or dkms zfs kernel packages at some point to my script and I'd be happy to tweak it so as to work (better) with zedenv so I'd be interested to hear your thoughts on it.

https://github.com/danboid/ALEZ

[johnramsden]

Cool, i'll try it out for my VM setup.

[danboid]

The ISO is on the releases page https://github.com/danboid/ALEZ/releases

[johnramsden]

@danboid Got it installed, I had some difficulties though and sent you a PR https://github.com/danboid/ALEZ/pull/3

I'm going to proceed to get zedenv-grub working, and write up some documentation.

[johnramsden]

@danboid Added some more usage info to readme.

Also tested, and successfully generated a BE for a bios setup. If you want to try it, you can install it with this PKGBUILD-git, just change the branch to grub-gen-squished from master here https://github.com/johnramsden/zedenv-grub/blob/183bc35aff500556d0b740357743d9bf9197e1c2/packaging/arch/PKGBUILD-git#L12.

Might have some issues still, i'll look again tomorrow.

[danboid]

Hi John

I've noticed that in one of your earlier replies for this PR you said " It's actually the grub.d/10_zfs_linux.py file though" but in your latest PKGBUILD-git ( https://github.com/johnramsden/zedenv-grub/blob/grub-gen-squished/packaging/arch/PKGBUILD-git ) file it still does this:

install -m 755 "grub.d/40_zedenv_custom" "${pkgdir}/etc/grub.d/40_zedenv_custom"

I want to test using the PKGBUILDS so I'll wait for you to fix this before I try installing and testing the grub plugin again. I can probably just install it fine with the python setup script but I thought we may as well go the whole hog and test the PKGBUILDs too.

[danboid]

I have so far successfully built and installed pyzfscmds and zedenv from their PKGBUILD-git files on my Arch ZFS VM installed from the latest ALEZ ISO.

If I need to check out and build alternate branches of zedenv-grub or anything else, then please provide the exact git commands to fetch the code you want me to try building and testing.

Thanks!

[johnramsden]

@danboid Still a few issues, but I'll let you know when they are sorted out and it's ready to use.

[danboid]

OK, thanks John!

[johnramsden]

@danboid I'm not sure if you happen to know this, but where does grub load the configuration from if it's saved in multiple clones? For example, your grub.cfg is saved in /boot/grub/ on zroot/ROOT/default, when you reboot into a new clone zroot/ROOT/default-2, and regenerate the configuration, where does a choose to read the configuration from? Does the config just have to be saved to every clone? Just the current one? I'm a bit confused at how grub figures out where to read it from when you are running all ZFS...

Guess I need to do some experimentation.

[danboid]

All I can think to say in reply to that is that PCBSD (which became TrueOS and is now called Project Trident or something) used to use GRUB. It had GRUB ZFS boot environment support but they eventually dropped GRUB for the FreeBSD bootloader in the TrueOS days because it "was more BSD" or something.

The question is, can you still download the code for or even just an ISO for one of the last releases of PCBSD / an earlier TrueOS release to at least see how it handled the GRUB config? Which version would be the best version to look at is another question I'm unsure of but I have found this:

http://download.pcbsd.org/iso/10.3-RELEASE/amd64/

I believe 10.3 was the last release of PCBSD (before it became TrueOS etc) and I'm 99% sure it used GRUB at that point.

[johnramsden]

Yeah I found their git repo and associated grub config. Trouble is finding where it is they save it to. Anyway, just to be safe I can just stick it in every clone.

[johnramsden]

Okay, now I'm stuck in grub rescue prompt with:

grub error file 'default' not found

Guess it didn't like that.

Whoops, figured it out I managed to delete zroot/ROOT/default by accident.

[danboid]

Have you looked at how OpenIndiana handles BEs? IIRC they use GRUB too but I have no real experience with OI/Solaris - it's hardware support is lacking.

EDIT

It seems OI switched to using the FreeBSD bootloader (from GRUB) for their 2016.10 release.

[johnramsden]

@danboid yeah I remember reading about Solaris making the change to FreeBSD's bootloader. I actually took a look at what it would involve to port the FreeBSD bootloader to Linux, but end up looking like a lot more work than I had hoped for. That would be really nice though since it as needed BE support.

Maybe we should move this conversation to #1 , since it's more related to that then documentation.

[danboid]

I've updated and tested the ALEZ ISO so now its time for the big test!

https://github.com/danboid/ALEZ/releases/tag/0.4

[danboid]

I'm following these instructions:

https://github.com/johnramsden/zedenv-grub/blob/docs/README.rst

It would seem this line is incorrect:

# zedenv set zedenv set org.zedenv:bootloader=grub

I expect that should be:

# zedenv set org.zedenv:bootloader=grub

[johnramsden]

@danboid Thanks, fixed.

[danboid]

New Arch ISO with the UEFI-friendly ALEZ

https://github.com/danboid/ALEZ/releases/tag/0.5

[johnramsden]

@danboid Thanks for your help with testing. I'm just going to confirm that the changes I made to make things work with a BIOS setup haven't broken the UEFI GRUB setup, and then I will proceed to merge everything into master.