Git-Mirrors/Qubes-Community-Content
1
0
Fork 0
mirror of https://github.com/Qubes-Community/Contents.git synced 2024-09-30 12:46:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update Autonomous Qubes-install (kickstart).md

Browse Source 
Various different improvements in the doc, however it'll need a few more updates before it's ready. I'll try squeeze in more before next summit if time allows it.
This commit is contained in:
Yuraeitha 2018-05-16 19:58:04 +00:00 committed by GitHub
parent 23c3c0aca2
commit 0c23b36067
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 72 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/hardware/Autonomous Qubes-install (kickstart).md
View File

@ -7,8 +7,15 @@ This doc is reaching toward completion, however, has some errors that need corre
## Introduction ##
The purpose of kickstart files is to install an operation system from start to end with less, or no human interaction at all. A kickstart file is therefore essentially a pre-configuration of any settings you may normally need to adjust during a normal Linux install. Here you may find instructions on how to get started with Qubes OS and kickstart files.
**Typical uses**
_List is not exhausted, there may be other uses not listed here. These are just the most common use-cases._
In order to avoid confustion, please note that the use of the wording kickstarter template does not refer to Qubes templates, but rather a simple configuration file, which when loaded will semi or fully Autonomously install Qubes (or fedora/redhat/cent).
<br />
**Typical uses**<br />
_The list is not exhausted, there may be other uses not listed here._
- Custom Qubes OS install.
- Please note that the kickstarter template does not use installer-default kickstarter layout, a layout which by default also is incomplete (evident by the settings and values you normally adjust during normal install of the operation-system, but are autonomously configured here in the kickstarter file).
- A greater degree of freedom to include/exclude commands, packages, or modify variables, which may otherwise not be changeable in the default installer. This gives you greater freedom to how you want your system to be set and organized.
- Swiftly installing or re-installing Qubes OS.
- May be used to smoothly and quickly recover should dom0 be suspected of any compromises.
- Various of scripts and automation can be included, to quickly restore everything in a clean state.
@ -27,44 +34,49 @@ _Once you constructed your kickstart file, using them is faster than via normal
<br />
## Kickstart Template ##
_You may find the kickstart template if you scroll a bit further down. Please modify personal settings, drives to install to, partitioning, or other variables._
## Kickstart Template - Introduction to basics ##
_This section provides an introduction to the basics, you may skip if you're an average terminal user, and if you know how to load a kickstart file in grub._
_This particular kickstart template will once initiated, install Qubes fully autonomously, without any human interaction, to the selected drive `sda` at /dev/sda, be sure you modify it to install on the correct drives. If you're not sure, then please disconnect other drives to ensure you do not mistakenly overwrite them._
This particular kickstart template introduced as a finished version in the example down below, will once initiated, install Qubes fully autonomously, without any human interaction to the selected drive. Be sure you put the correct drives and configurations. If you're not sure, then please disconnect other drives to ensure you do not mistakenly overwrite drives and their potential valuable data.
_Users who have NVMe disks, please replace `sda` with `nvme0n1`. Keep in mind if you got more than one NVMe drive, that this changes nvme0n**X**p**Y** in a similar fashion to normal sd**XY**. For example `nvme0n3` is equivalent to `sdc`, and `nvme0n3p4` is equivalent to `sdc4`._
Users who have NVMe disks, please use `nvme0n1` instead of `sda`. Keep in mind if you got more than one NVMe drive, that this changes nvme0n**X**p**Y** in a similar fashion to normal sd**XY**. For example `nvme0n3` is equivalent to `sdc`, and `nvme0n3p4` is equivalent to `sdc4`.
_Once installed, and Qubes is booting for the first time, and if you're asked to put a new username please use the same user-name in the Qubes initial-setup as you have put in your kickstart file._
Once installed, and Qubes is booting for the first time, and if you're asked to put a new username please use the same user-name in the Qubes initial-setup as you have put in your kickstart file.
_Kickstart files are very easy to use and initiated. Whether on the installer medium or on a seperate medium, you just need to include the kickstart file location in the installer command line. For Qubes 4, press the Tab key at early Qubes installer boot stage, before you start the installer. Insert `ks=hd:sda:/ks.cfg`. Keep in mind it can be modified logically. If the ks.cfg is named differently, if its in a folder, if you're using a different device (like for example sdc4), or you're pulling it from a network location, etc. Please look it up if more is needed to config._
Kickstart files are very easy to use and initiated. Whether on the installer medium or on a seperate medium, you just need to include the kickstart file location in the installer command line. For Qubes 4, press the Tab key at early Qubes installer boot stage, before you start the installer. Insert `ks=hd:sda:/ks.cfg`. Keep in mind it can be modified logically. If the ks.cfg is named differently, if its in a folder, if you're using a different device (like for example sdc4), or you're pulling it from a network location, etc. Please look it up if more is needed to config.
_Copy and paste the below into a text editor, use nano, vi, or which text editor you prefer. Edit it to your needs, don't run it without first checking account details and drive install location. The name of the kickstart file is optional, but it must always end with `.cfg`. Naming it `ks.cfg` is recommended. Simply move it to anywhere the installer can reach it when booting, whether using the same medium or an extra separate medium._
Copy and paste the below into a text editor, use nano, vi, or which text editor you prefer. Edit it to your needs, don't run it without first checking account details and drive install location. The name of the kickstart file is optional, but it must always end with `.cfg`. Naming it `ks.cfg` is recommended. Simply move it to anywhere the installer can reach it when booting, whether using the same medium or an extra separate medium.
You may use any terminal to identify a second medium's location. But remember if you unplug, or shutdown the machine after plugging in two or more medium devices, that their hierarchy may change. Sometimes a machines BIOS/UEFI may behave oddly in this manner. Keep this in mind if you cannot start/load the kickstart file. Installer will inform you before it starts making changes to the drive, if the kickstart file cannot be found, or if there are instructions it cannot understand in the kickstart file.
## Kickstart Template - Adjusting your modifications ##
_All variables that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language. Scroll below the template to find instructions on how to adjust values, revoming or including commands, package inclusion, etc._
_You may use any terminal to identify a second medium's location. But remember if you unplug, or shutdown the machine after plugging in two or more medium devices, that their hierarchy may change. Sometimes a machines BIOS/UEFI may behave oddly in this manner. Keep this in mind if you cannot start/load the kickstart file. Installer will inform you before it starts making changes to the drive, if the kickstart file cannot be found, or if there are instructions it cannot understand in the kickstart file._
```
# Kickstart file, preconfiguring the Qubes installer settings.
# Initializing installer
auth --enableshadow --passalgo=sha512
cdrom
text
# Protective measures
ignoredisk --only-use=sda
firewall --service=ssh
# Protective measures, including redundancy measures.
ignoredisk --only-use=change
firewall
network --hostname=dom0
authconfig --enableshadow --passalgo=sha512
sshpw --lock
rootpw --lock
# Account details
keyboard --vckeymap=us --xlayouts='us'
lang en_US.UTF-8
timezone Europe/London --isUtc
user --groups=wheel,qubes --name=change-name-here --password=change-pwd-here
keyboard --vckeymap=change --xlayouts='change'
lang en_change.UTF-8
timezone change/change --isUtc
user --groups=wheel,qubes --name=change --password=change --iscryped
# Disk and Partitioning
bootloader --location=mbr --boot-drive=sda
clearpart --all --initlabel --drives=sda
bootloader --location=mbr --boot-drive=change --password=change --iscrypted
clearpart --all --initlabel --drives=change
autopart
# Boot settings
@ -86,7 +98,31 @@ pwpolicy luks --minlen=0 --minquality=1 --notstrict --nochanges --emptyok
```
<br />
## Extra configurations ##
## Adjusting credentials and encryption ##
- **All variables** that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language.
- **Securing passwords** - The kickstart file can include passwords in plaintext, in which you simply write your password directly in the kickstarter file (not recommended), or with encrypted format (recommended). The ´--plaintext´ flag after passwords will instruct the use of plaintext in password databases, while ´--iscrypted´ flag after passwords will instruct to use hashed password values.
- **Note that pre-hashing your passwords** is important if your kickstart file is ever discovered. It may be best to assume the worst, so it is recommended to always use --isencrypted flag and include the hashed password values.
- **Basics of salt encryption** - Only creating hash values for your passwords is not enough to protect them, further protective measures are needed to increase the difficulty to gaining access, especially if you're using a short non-truly random password. This can be done by using salt encryption, which will generate a different hash value, even if you re-generate the same salt salted password again. Note that it will work on different machines even if the same password uses a different hash value, this is because the salted hash value includes the encrypted instructions that the encryption algorithm will read and understand, and ultimately in a more secure manner obtain the real hash for your password. Therefore it's fine to create your salted passwords elsewhere, whether on the same or a different secured system. Salt encrypted hashed passwords can only be understood by the legitimate programs, so be sure you do not mix them up with each others below. User login for grub2 encrypyion is always root. If you're curious to learn more, then you may find extra reading in the external sources headline further down below.
- **Grub2 encryption** - If you need to generate a hash password for the ´--iscrypted´ flag, then you can generate grub2 salted hash values in any secure terminal with grub2 installed. You may freely use any system, however make sure it is not compromised. Copy the whole line, starting from ´grub.pbkdf2.sha512...´.
- **Protecting the user-account** - Similar as for enhanced grub2 encryption, you may use ´--iscrypted´ to your user Linux profile, but keep in mind that Linux uses a different salt algorithm from grub2, so you'll need to adjust accordingly. Copy/paste this termianl to a clean dispVM, or use a clean fresh AppVM; `python -c 'import crypt,getpass;pw=getpass.getpass();print(crypt.crypt(pw) if (pw==getpass.getpass("Confirm: ")) else exit())'`. Just like with grub2, it'll ask for a password and a confirmation, before printing your salted hash. Copy/paste your hash value into the kickstart file user account password field.
- **Account name** - If you haven't already donr so, feel free to change it to any desired name.
- **LUKS disk encryption** - Will be included before official Qubes doc PR.
- **If you prefer not to encrypt grub2** - To disable, remove `--password=change --iscrypted` from the bootloader kickstarter line.
- **If you prefer not to encrypt disk** - Will be included before official Qubes doc PR.
## Adjusting drive letters ##
- All variables that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language.
- Will be included before official Qubes doc PR.
## Adjusting timezones and language ##
- All variables that needs changing, are labelled `change`, which include credentials, drive letters, timezones, language.
- Will be included before official Qubes doc PR.
## Adjusting included packages ##
**Optional package list**
_List is not finished, will be updated._
```
@ -103,6 +139,9 @@ _List is not finished, will be updated._
@anaconda-tools
```
## Including or excluding kickstart commands ##
- Will be included before official Qubes doc PR.
## Kickstart uses gone wrong - Examples to avoid ##
- Keep any fully autonomous kickstart USB's, or the medium of choice, locked-up, properly labelled, or avoid other scenarios where it may mistakenly be booted, by you or someone else.
@ -131,18 +170,26 @@ _List is not finished, will be updated._
## Insight, guides, and other external resources ##
- **Resources**
- Official Anaconda kickstart developer documentation guide
- Official Anaconda kickstart developer documentation guide<br />
https://github.com/clumens/pykickstart/blob/master/docs/kickstart-docs.rst
- Official Fedora Kickstart guide (Adjusted for fedora 27)
- Official Fedora Kickstart guide (Adjusted for fedora 27)<br />
https://docs.fedoraproject.org/f27/install-guide/advanced/Kickstart_Installations.html.
- Official RedHat Documentation guide
- Official RedHat Documentation guide<br />
https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/installation_guide/ch-kickstart2
- Wiki - Salt Cryptography<br />
https://en.wikipedia.org/wiki/Salt_(cryptography)
<br />
- **Qubes resources**
- Here you may find the post this doc originally was inspired from.<br />
https://groups.google.com/forum/#!msg/qubes-users/-9qRHSkwfy8/CCx08nnTVEAJ
<br />
## Kickstart files are sometimes controversial in culture ##
Some label them for advanced users only (being too difficult to use), while others label them for noobs, or newbs, only. The beliefs, or statements, are contradictionary to each others. In reality though, kickstart files can be useful for anyone, whether made for someone who is not very skilled with computers, or useful for someone who is an advanced computer user. So it is best to keep it that way, kickstart files are useful tools that everyone can use in some way or another, don't let silly culture conjuncture influence what you use, if it is useful to you. Furthermore, anyone who have the skill level to install and use Qubes on their own, can probably also build and use their own kickstart files. They're not as scary as they might seem at first.
<br />
## Consideration before submitting updates to this doc ##
This doc is originally submitted by the independent volunteer group Qubes Community Collaboration. You're free to submit improvements on your own, but you can also go through our channels at https://github.com/Qubes-Community/Contents/issues if you would like to improve the doc with our volunteer collaboration. If its your first time submitting docs and you would like to be be independent, then we still recommend you get some experience through our channels first, before submitting anything officially for quality review by the Qubes staff. Of course you're also welcome to join our volunteer efforts as a collaboration.
This doc is originally submitted by the fully independent volunteer group, Qubes Community Collaboration (QCC). You're naturally free to submit improvements of this doc to the Qubes OS staff for review on your own , but you can also choose to go through our channels at https://github.com/Qubes-Community/Contents/issues if you would like to improve the doc through the community collaboration. Feel free to start up an issue at QCC to discuss this doc and how to proceed. This potentially saves the Qubes OS staff time and resources, while still preserving transparency, and it helps improving doc PR summits further when worked out, improved, and shaped by a community. If its your first time submitting to GitHub but you would like to be independent, then we at QCC still encourage you get some GitHub experience through our channels first, before submitting anything official Qubes OS on your own. Credit to author(s) will always be preserved.