From dd0c585fc3f2ee18c1b56b05c0bd9cd7e3734d0b Mon Sep 17 00:00:00 2001 From: Sally Makin Date: Mon, 14 Aug 2023 11:36:26 +0100 Subject: [PATCH] Add content and change to reST - Add content from /documentation folder into Diataxis structure - Change all content from .md to .rst - Add some tutorial content from Server docs - Move introduction to top-level navigation to make it easier to find - Update README.md with instructions for building local docs --- doc/README.md | 10 + doc/explanation/configure-storage.rst | 177 +++ .../basic-installation-start-screen.png | Bin 0 -> 3438 bytes .../configure-storage-GPT-partition.png | Bin 0 -> 4453 bytes .../configure-storage-boot-devices.png | Bin 0 -> 2244 bytes .../configure-storage-guided-options.png | Bin 0 -> 2961 bytes .../figures/configure-storage-lvm.png | Bin 0 -> 3559 bytes .../figures/configure-storage-main-screen.png | Bin 0 -> 5788 bytes .../figures/configure-storage-partitions.png | Bin 0 -> 2227 bytes .../figures/configure-storage-raid.png | Bin 0 -> 3965 bytes doc/explanation/index.rst | 6 + doc/explanation/operate-server-installer.rst | 96 ++ doc/howto/autoinstall-quickstart-s390x.rst | 125 ++ doc/howto/autoinstall-quickstart.rst | 183 +++ doc/howto/index.rst | 16 +- doc/howto/report-bugs.rst | 58 + doc/index.rst | 1 + doc/{tutorial => }/intro-to-autoinstall.rst | 0 doc/reference/autoinstall-reference.rst | 1161 ++++++++++++++--- doc/reference/autoinstall-schema.rst | 589 +++++++++ doc/reference/index.rst | 11 +- doc/tutorial/basic-server-installation.rst | 123 ++ .../basic-installation-start-screen.png | Bin 0 -> 3438 bytes doc/tutorial/figures/sbs-complete.png | Bin 0 -> 6803 bytes doc/tutorial/figures/sbs-confirm-storage.png | Bin 0 -> 3801 bytes doc/tutorial/figures/sbs-identity.png | Bin 0 -> 2484 bytes doc/tutorial/figures/sbs-keyboard.png | Bin 0 -> 1832 bytes doc/tutorial/figures/sbs-language.png | Bin 0 -> 3438 bytes doc/tutorial/figures/sbs-logs.png | Bin 0 -> 4731 bytes doc/tutorial/figures/sbs-mirror.png | Bin 0 -> 2041 bytes doc/tutorial/figures/sbs-network.png | Bin 0 -> 3063 bytes doc/tutorial/figures/sbs-proxy.png | Bin 0 -> 2755 bytes doc/tutorial/figures/sbs-refresh.png | Bin 0 -> 2980 bytes doc/tutorial/figures/sbs-snaps.png | Bin 0 -> 9309 bytes doc/tutorial/figures/sbs-ssh.png | Bin 0 -> 2328 bytes doc/tutorial/figures/sbs-storage.png | Bin 0 -> 3982 bytes doc/tutorial/index.rst | 8 +- doc/tutorial/screen-by-screen.rst | 174 +++ 38 files changed, 2560 insertions(+), 178 deletions(-) create mode 100644 doc/explanation/configure-storage.rst create mode 100644 doc/explanation/figures/basic-installation-start-screen.png create mode 100644 doc/explanation/figures/configure-storage-GPT-partition.png create mode 100644 doc/explanation/figures/configure-storage-boot-devices.png create mode 100644 doc/explanation/figures/configure-storage-guided-options.png create mode 100644 doc/explanation/figures/configure-storage-lvm.png create mode 100644 doc/explanation/figures/configure-storage-main-screen.png create mode 100644 doc/explanation/figures/configure-storage-partitions.png create mode 100644 doc/explanation/figures/configure-storage-raid.png create mode 100644 doc/explanation/operate-server-installer.rst create mode 100644 doc/howto/autoinstall-quickstart-s390x.rst create mode 100644 doc/howto/autoinstall-quickstart.rst create mode 100644 doc/howto/report-bugs.rst rename doc/{tutorial => }/intro-to-autoinstall.rst (100%) create mode 100644 doc/reference/autoinstall-schema.rst create mode 100644 doc/tutorial/basic-server-installation.rst create mode 100644 doc/tutorial/figures/basic-installation-start-screen.png create mode 100644 doc/tutorial/figures/sbs-complete.png create mode 100644 doc/tutorial/figures/sbs-confirm-storage.png create mode 100644 doc/tutorial/figures/sbs-identity.png create mode 100644 doc/tutorial/figures/sbs-keyboard.png create mode 100644 doc/tutorial/figures/sbs-language.png create mode 100644 doc/tutorial/figures/sbs-logs.png create mode 100644 doc/tutorial/figures/sbs-mirror.png create mode 100644 doc/tutorial/figures/sbs-network.png create mode 100644 doc/tutorial/figures/sbs-proxy.png create mode 100644 doc/tutorial/figures/sbs-refresh.png create mode 100644 doc/tutorial/figures/sbs-snaps.png create mode 100644 doc/tutorial/figures/sbs-ssh.png create mode 100644 doc/tutorial/figures/sbs-storage.png create mode 100644 doc/tutorial/screen-by-screen.rst diff --git a/doc/README.md b/doc/README.md index 5e3ad891..91513c4c 100644 --- a/doc/README.md +++ b/doc/README.md @@ -9,3 +9,13 @@ documentation. As the RTD version is not yet ready, documentation changes should be made to `../documentation` until this README is updated to say otherwise. As such, please make any desired documentation changes to `../documentation`. + +# Local preview + +To build this documentation, you can run `make install` from this folder to +create the virtual environment. + +Then run the `make run` command, which will build a html version of the docs, +and serve the docs in the virtual environment. This is very convenient if you +are working on them and want your saved changes to be reflected as a working +preview. diff --git a/doc/explanation/configure-storage.rst b/doc/explanation/configure-storage.rst new file mode 100644 index 00000000..5e460055 --- /dev/null +++ b/doc/explanation/configure-storage.rst @@ -0,0 +1,177 @@ +.. _configure-storage: + +Configuring storage +******************* + +There are a lot of options for storage configuration with the Subiquity +installer. This guide will walk you through some of the common options for an +Ubuntu Server installation. + +Guided options +============== + +.. image:: figures/configure-storage-guided-options.png + :alt: + +Selecting "Use an entire disk" on the Guided storage configuration screen will +install Ubuntu onto the selected disk, replacing any partitions or data already +there. + +You can choose whether or not to set up LVM, and if you do, whether or not to +encrypt the volume with LUKS. If you encrypt the volume, you need to choose a +passphrase that will need to be entered each time the system boots. + +If you select "Custom storage layout", no configuration will be applied to the +disks. + +In either case, the installer moves onto the main storage customisation screen. + +The main storage screen +======================= + +.. image:: figures/configure-storage-main-screen.png + :alt: + +This screen presents a summary of the current storage configuration. Each +device or partition of a device corresponds to a different row (which can be +selected), and pressing :kbd:`Enter` or :kbd:`space` while a device is selected +opens a menu of actions that apply to that device. + +Partitions +========== + +.. image:: figures/configure-storage-partitions.png + :alt: + +To add a partition to a device, select "Add GPT Partition" for that device. + +.. image:: figures/configure-storage-GPT-partition.png + :alt: + +You can leave "Size" blank to use all the remaining space on the device. + +RAID +==== + +.. image:: figures/configure-storage-raid.png + :alt: + +`Linux software RAID `_ +(where RAID stands for "Redundant Array of Inexpensive Disks") can be used to +combine several disks into a single device that is (usually) tolerant to any +one disk failure. + +A software RAID device can be created out of entire disks or unformatted +partitions. Select the "Create software RAID ("MD")" button to open the +creation dialog. + +The server installer supports devices with RAID level 0, 1, 5, 6 or 10 being +created. It does not allow customising other options such as metadata format or +RAID10 layout at this time. See the +`Linux RAID documentation `_ +for more details. + +A software RAID device can be formatted and mounted directly, can be +partitioned into several partitions, and can even be used as part of another +RAID device or LVM volume group. + +Logical Volume Manager (LVM) +============================ + +.. image:: figures/configure-storage-lvm.png + :alt: + +The LVM is a system of managing logical volumes, or filesystems, that is much +more advanced and flexible than the traditional method of partitioning a disk +into one or more segments and formatting that partition with a filesystem. It +can be used to combine several disks into one larger pool of storage but it +offers advantages even in a single disk system, such as snapshots and easy +resizing of logical volumes. + +As with RAID, a LVM volume group can be created out of entire disks or +unformatted partitions. Select the "Create LVM volume group" button to open +the creation dialog. + +Once a volume group has been created, it can be divided into named logical +volumes which can then be formatted and mounted. It generally makes sense to +leave some space in the volume group for storage of snapshots and creation of +more logical volumes as needed. + +The server installer does not supported configuring any of the many, many +options that LVM supports when creating volume groups and logical volumes. + +Selecting boot devices +====================== + +.. image:: figures/configure-storage-boot-devices.png + :alt: + +On all architectures other than s390x, the bootloader needs to be installed to +a disk in such a way that the system firmware can find it on boot. By default, +the first device to have a partition created on it is selected as a boot device +but this can be changed later. + +On amd64 and arm64 systems, multiple disks can be selected as boot devices, +which means a system can be configured so that it will continue to boot after +a failure of any one drive (assuming the root filesystem is placed on a RAID). +The bootloader will be installed to each of these drives, and the operating +system configured to install new versions of GRUB to each drive as it is +updated. + +amd64 systems use GRUB as the bootloader. amd64 systems can boot in either UEFI +or legacy (sometimes called "BIOS") mode (many systems can be configured to +boot in either mode) and the bootloader is located completely differently in +the two modes. + +Legacy mode +----------- + +In legacy mode, the bootloader is read from the first "sector" of a hard drive +(exactly which hard drive is up to the system firmware, which can usually be +configured in a vendor-specific way). The installer will write GRUB to the +start of all disks selected as a boot devices. As GRUB does not entirely fit +in one sector, a small unformatted partition is needed at the start of the +disk, which will automatically be created when a disk is selected as a boot +device (a disk with an existing GPT partition table can only be used as a boot +device if it has this partition). + +UEFI mode +--------- + +In UEFI mode, the bootloader loaded from a "EFI System Partition" (ESP), which +is a partition with a particular type GUID. The installer automatically creates +a 512MiB ESP on a disk when it is selected as a boot device and will install +GRUB there (a disk with an existing partition table can only be used as a boot +device if it has an ESP -- bootloaders for multiple operating systems can be +installed into a single ESP). UEFI defines a standard way to configure the way +in which the operating system is chosen on boot, and the installer uses this to +configure the system to boot the just-installed operating system. One of the +ESPs must be mounted at ``/boot/efi``. + +Supported arm64 servers boot using UEFI, and are configured the same way as an +UEFI-booting amd64 system. + +ppc64el systems also load their bootloader (Petitboot, a small linux kernel) +from a "PReP" partition with a special flag, so in most ways they are similar +to a UEFI system. The installer only supports one PReP partition at this time. + +Limitations and workarounds +=========================== + +Currently, the installer cannot **edit** partition tables. You can use existing +partitions or reformat a drive entirely, but you cannot (for example) remove a +large partition and replace it with two smaller ones. + +The installer allows the creation of LVM volume groups and logical volumes and +MD raid devices, but does not allow tweaking of the parameters -- for example, +all logical volumes are linear and all MD raid devices use the default metadata +format (1.2). + +These limits can both be worked around in the same way: drop to a shell and use +the usual shell commands to edit the partition table or create the LV or RAID +with desired parameters, and then select these partitions or devices as mount +points in the installer. Any changes you make while the installer is running +but before altering the storage configuration will reflected in the installer. + +The installer cannot yet configure iSCSI mounts, ZFS at all, or btrfs +subvolumes. diff --git a/doc/explanation/figures/basic-installation-start-screen.png b/doc/explanation/figures/basic-installation-start-screen.png new file mode 100644 index 0000000000000000000000000000000000000000..845d68d23012e4e7a8b69da7e15d7b8dd3ad9bb5 GIT binary patch literal 3438 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 literal 0 HcmV?d00001 diff --git a/doc/explanation/figures/configure-storage-GPT-partition.png b/doc/explanation/figures/configure-storage-GPT-partition.png new file mode 100644 index 0000000000000000000000000000000000000000..afadcbdd7bc3b64376703795066673d04d56ae1a GIT binary patch literal 4453 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 literal 0 HcmV?d00001 diff --git a/doc/explanation/figures/configure-storage-boot-devices.png b/doc/explanation/figures/configure-storage-boot-devices.png new file mode 100644 index 0000000000000000000000000000000000000000..cc291c76c48123ea8fd1a5af4a4e7effd0cd48cc GIT binary patch literal 2244 zcmV;#2s`(QP)7Pd-#xRC4yn0w{7sp^SJx-Iw z@kY!nm@FD&O_S+yalDmArw{~z2qt11c)_ix+hEchEAYft+)kqtn%5r9^9D!rAXxys z4-L*k6_gKs_6WLywn!Llk=#O?1klzRVoeckTRE$Hl$7pSYFA?=fL=ZO8)%c@7trAH zya%Cq_n`%sC4V=gl>=Dh+GwYAG-y5|39tLc1ZpTC~1;v_EN@@>ZOk0F+8+ z1Lc#ZIa;1E{%TKqMSClw(ShAc=oz6YDYTOK>Wl^@^kvX^3(;bOwmzBC*-*BO2A^^E zCu@Z!2u<`rgDe>63(z z;6%Dx6=<<7wQSu`YL#wa&_t+2M>HrggSNM5X@N#CaV=U?TT9Ev!=lN~XwdL28aMQ- zXeq|BaSQ7K#sduq8IOI{t`*(D>0@%)WMFo<1@ASrDtPZ!#^fGWWIVp;_!sV(^1*X# zZpq|+Rnfp~L~J~qjsw-9d8pZa{=yjAbD(>&;f05eiW(MGi5H&O3wyNEinc70jb!t2t88_pt~tQR&>)|1_6aF+TKJ1wXe?|Yl5f#+@qsdj12VtC)uo?vJe#7UQA{D- zLUC-fNFWuX8D)>pI-+jX&A&wReS_xvc+E=A!ncsoR0*w6HQgnaj(^qA7z`sG7>By`nCj4H|E$TwukP0c}I&t%p=iVX8$d@g`cKaZAQlMkxwbt8z4T4Gpqj zpe3TAysC0NPH<(GOAVKeb2OKv^%}IOTsgLrMJjK-Zlpv5nr`R@YUwDx<});1Mzf7s zi?E^8D&4@Anlxy*RgZSo4WPsfns3o$E3~GzCd-DP3)-3SfQE0;OwUDTJLdqAJP6TH18ino7w5A^J-|NIo-`446KKOiN*Pu zkF(rcKNwgK#bFR8sUK|~+Zk97MVS^}AEGbX6mYSH}8Xph!I(Rff>Tef;eW*pu}v=Qx@Xs@&aUe)pn-C&VSw$tN+yd%-M^9g9x zF=kR4g*^0m3!aKLB_$NU5$!#}eT(J^a-E&epMn;U63UaVMKWjkktbnWcBk{ar=X!8 zTA*2Fl#Ul@??2BdHFU%N#_B_VKJ*~XOO1R5Nm_dvTEKFnN6x?{w17(uk4%E+bb}jc z-V@RCZZO&AZB10VK|nsG+ou_i;CqS&Heoc}XEZdqG?Zwic^DeEpbBY?!Z+HIG-$XyKxk1HH0w@mz4}hY z@lE05SA#~G8#L0V5JKd#7r8MMXtD=dmP1inyFkmXp+Q!-`h^*~77bNP(niq%^&G8R zg=Xl)xmz8wYN_p3KnrNQ)fF^lv^+2z294Htup6k$QtQ|a)^YxQR-qZA#m(KIf+pLb zbu=Ei&uNzSL6f-pWg2~sMmnkO24p9!eUM zi>qW^(Q=3Mj6F|xyoXz0Ho$bOnv6%c2Y0x}e|Ml7XCC7$_vvU+*G|x_8{C6dKVPd) zQiGjyRHymcooJWywNjF@9?c&Ltvp|&M^Io`n$dG??h?;o4E{p`e7>#A@P04a#e9t( zr}>~g#piq;K?OeF)?rd~*Z;3w&ezV+iU*h&?QPis?cVNPov%q{&}govl&D41gP|3Z zq5=)~TwO(TRHymc-Dt8IO^SLnF(8_quQ~kh8$P!+k_+J+J!%Oh$iAL~p;hN=4*&bc z5@u#RSEFrfl*(7eG6thM)=+||7+Z-_iC9XsTBMAOT03dAqN+`4ORLOV zYYBo@#1_-iGSVuErL`WUR4gTG3+nC6oSvEYFL>_{pXc7sx#ynyJfG)$?oB)4<|woO z(0&OC2^l9W##2H93`j_TPC>w5GG|ZyX8#4`PPlkE$ji&mdI7t;yP=_>d-m)xZM%3@ zLPF}86UNr-;?Tk;M1`dX@@3I&-Of_;4brX45{mm&{puVxtFNUqyGT z4*tyPU7B&14RO0<*ZiY<(=dq)%&_WMkfYkJe>91>J2~9&CuLBf7-pN!gv7({v*OTJIxTLX%Zi~qzhFjS*3ar-u6i< z%#cC%t&QR94UvU9P@c7KoXGsb_f(gx1Xz2LGr$*oHUp(Chzigp4a0WjZm)9D&p9#O zOws{tV)LtAAJF}-@#UB3a%)Z3-%3}}(`o2rrA~`qCSy^n<{t%|`Mz9(c7FWx?MpiJ z!5CqXvgMnsEvrLoZa6j0%Q!B)`p{Yl+H+TNI(=@rC)>+5dA@ouDOp?{%S_0K|2%T* zeJ%%OVY9=?8fErgTHi?BnpKiZ98Ng$x8{4Oa2QOW3fl8$RV04D(m;FrGS0R9eg-Sy zl%)S6W7`@|^u<8u1~S}BTNAf&AJ|3<{tBZzb!e9XZ)e~Ndc>i>4N?fmSJD#L87q%dNut`Y`~$RvI5&BIyp$`qf1NK*{Dd#3yx;8mhRaCu0v-kFo7_yh zelKh}f*5HsX6Dfg_uEdlKf%){OlPwfjgM6khRss(ah%$lwPR~_`UoGRh3wr|=;$dg zDs~^{8ujT)(Y?nd2B6ysRIj=6K^zpxjSEr6Zi#m>K*3^|(h=GAmhIj#2y#*#()sEcC~v|o8EJ3;KspEpTFTr@)q|O z50hSOaadOq{YyEpcEK-zwjQ-_OJqJ8B2UY)Hm9p5VaM{`r9vn3QS*&I8Wt+`Zso<} zwKGzpfpZ1k_xQX(BH+#PUqDeRQIwX^GA{HNVceHvgvf`drh z1#ghX8FUj2e3C5b_ZS}sS18Ql!``Jc8TY;ICtFv8qB?>tr|bIzYDAQ-{0>(4xI6BF z+FzCXD_p=V+dN&+;SL2}?k#E!K8gyAAl$46Pq44nL!uM1H0a~=H7>=B2BTS_k+@MN zgQ656llG!fUM@9cDvBCYyeGXeBe5tEXP+r+bPy-b41g4v?k}>SH5z8>7E2|0xLf&U z%Lrkxe9`)0u6G&{=91~WreUEC(C&m6KX+X$nK^!cQkL>629JgA{6ourQh|M zx5InZ_*c9>S>BYSWhhpms;!n#YK;VZPYVj)-Gvf8!VDc7cw728~f(Ra=iu>>^s+F60lfs zj*AwC>B48hQSz0HvI^_ggi-R_+NuevHW&_K^B73w0U zUX}$ra}9Z?q%dYF4Ua9J#RH84ji`s=3j?qevHQI|pg;9NCc2TlAsP{#aIoV{@#6dVjuREVs;g^N+eC_0C8jxKSm(P^NRE`dA z0Q7Ta-h&tK5Jx8QNbkzpO2afQSqpj{xMH8CX2D`CSe^_HJ7+y&fOv=x$O=)T!8^Nt z&}(h_xEHx#`;PM3kti_~0Q&Z>d69=1HT*+g{a&8`XKbT2M$GlU0W#8{8?=qF^e6h_vqC5Ol(WI8nKu(+vmg7MfRIGh%WT;tKWJvwG>M3zRy*dad_cX^=;7Gre#Lf znf|U%P2W}ZKbhNNoM}e*!Tx2>C5yGe8?^1|-L{2n?rt3G>_qfSp{i~S)Mk+Zt_j_o z-hS3yhV7t^4C^mKPp_LYNx=7Nf3Ov>RZ~5l+}r1|o-(wL3~+DE@fDIxT3Axbw^V6R zjc42K^A$eeR4N8d>%Rm%DL+1fTC<#%ikV-;yJ)ST_5#NqMUt9Q_X zP+*mE+_aB6B9nqiR>6)Ak{^S8WiV#ak}%DdElL2Oy#;=R8$W>6pROU5j;(8`3ef}L zFAT-cj$}J`+<$(A;$h~QL?1Z;ojk-em|UPpwGa^jc_X{R_BCmzGH_gcD2M4$2LAh{ z_{%eZWiNyrzCCvrEz2_Tg9*-3{g|1_Zlxledp7^-%lMPP>o>*XvJ%D4^ILST?qc}^ zcvlSX;w()V-_m&!Q{@W8iD%=r=suDPtY7Ka!`KIII=lDKq94koG$Rc@X)vV)eZL4T z=!$vb1Tmdktg<$3UE~4{$o&=l)wBP`4MtV%dwrEY6>F0#=LdNZk@xGgV7J`tXE<=0 z4g^*j!A{8n`?Zy+h*wTWaVln@$jv({gFUG!{4)Yv&IL|IJp>u;l!VwPc?^@WWu*lWq@w*A~TLk&{Q{Fmnqe0$|$g4A_hZQ&e)U=djZoo!J@W zo%jdW2vJXJPx@ZeH!wVnCr52~09prJ*IiczvPyh&932>yU834m)KU&Q1dcUvb&;gP zs8%}gWfHJpEFUFDWfSVSNO~y*$&oI)fA2D5_#ts%1+{96;JKw!bM!&-I8dCR+Q;Ez ztPojH5NCW6RZ>>E2C|qswi`Mzt$jCUF8p13}ir|C4b!0wi)<*~B|G+SK zEcDZ}TXI*v68wLnxpaMt^JD%w_mG;~v4Vo9Lo48S{4R*-I=a1`=tXSLL*IncuIJ#{ zTJ%B)5)$2v9@!@dB*2nj)Ig*8VmXT;sQtRtwidm9f}toO@u6?|RS=Vm=s!B2^je1k zvcLn2%WaPoI^{vSHpc_>W=K6m_6J|_n^OqE^W<^KZRohhvV literal 0 HcmV?d00001 diff --git a/doc/explanation/figures/configure-storage-lvm.png b/doc/explanation/figures/configure-storage-lvm.png new file mode 100644 index 0000000000000000000000000000000000000000..85279bc2b378aa9a5d9149c531cbfbfaf61d2630 GIT binary patch literal 3559 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 nCHk8uvX{8jZ(mU%LX=rFz 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 BDO~^n literal 0 HcmV?d00001 diff --git a/doc/explanation/figures/configure-storage-raid.png b/doc/explanation/figures/configure-storage-raid.png new file mode 100644 index 0000000000000000000000000000000000000000..712f8bbd4e4e4ad08d623a80d072eec6954b73c7 GIT binary patch literal 3965 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 literal 0 HcmV?d00001 diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst index fd7a2c2f..08e02bee 100644 --- a/doc/explanation/index.rst +++ b/doc/explanation/index.rst @@ -7,5 +7,11 @@ knowledge and become better at using and configuring Subiquity. ----- +About the Server installer +========================== + .. toctree:: :maxdepth: 1 + + operate-server-installer + configure-storage diff --git a/doc/explanation/operate-server-installer.rst b/doc/explanation/operate-server-installer.rst new file mode 100644 index 00000000..95e725f1 --- /dev/null +++ b/doc/explanation/operate-server-installer.rst @@ -0,0 +1,96 @@ +.. _operate-server-installer: + +Operating the Server installer +****************************** + +This document explains how to use the installer in general terms. For a +step-by-step guide through the screens of the installer, you can use our +`screen-by-screen reference guide `_. + +Get the installer +================= + +Installer images are made (approximately) daily and are available from +https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/. These are not +tested as extensively as the images from release day, but they contain the +latest packages and installer, so fewer updates will be required during or +after installation. + +You can download the server installer for amd64 from +https://ubuntu.com/download/server and other architectures from +http://cdimage.ubuntu.com/releases/20.04/release/. + +Installer UI navigation +======================= + +In general, the installer can be used with the :kbd:`up` and :kbd:`down` arrows +and :kbd:`space` or :kbd:`Enter` keys and a little typing. + +:kbd:`Tab` and :kbd:`Shift` + :kbd:`Tab` move the focus down and up respectively. +:kbd:`Home` / :kbd:`End` / :kbd:`Page Up` / :kbd:`Page Down` can be used to +navigate through long lists more quickly in the usual way. + +Running the installer over serial +================================= + +By default, the installer runs on the first virtual terminal, ``tty1``. This +is what is displayed on any connected monitor by default. However, servers do +not always have a monitor. Some out-of-band management systems provide a +remote virtual terminal, but sometimes it is necessary to run the installer on +the serial port. To do this, the kernel command line needs to +`have an appropriate console `_ +specified on it -- a common value is ``console=ttyS0`` but this is not +something that can be generically documented. + +When running on serial, the installer starts in a basic mode that uses only +the ASCII character set and black and white colours. If you are connecting from +a terminal emulator such as gnome-terminal that supports Unicode and rich +colours you can switch to "rich mode" which uses Unicode, colours and supports +many languages. + +.. _connect-via-ssh: + +Connecting to the installer over SSH +==================================== + +If the only available terminal is very basic, an alternative is to connect via +SSH. If the network is up by the time the installer starts, instructions are +offered on the initial screen in basic mode. Otherwise, instructions are +available from the help menu once networking is configured. + +In addition, connecting via SSH is assumed to be capable of displaying all +Unicode characters, enabling more translations to be used than can be displayed +on a virtual terminal. + +Help menu +========= + +The help menu is always in the top right of the screen. It contains help -- +both general and for the currently displayed screen -- and some general actions. + +Switching to a shell prompt +--------------------------- + +You can switch to a shell at any time by selecting "Enter shell" from the help +menu, or pressing :kbd:`Control` + :kbd:`Z` or :kbd:`F2`. + +If you are accessing the installer via ``tty1``, you can also access a shell +by switching to a different virtual terminal (:kbd:`Control` + :kbd:`Alt` + +arrow, or :kbd:`Control` + :kbd:`Alt` + number keys, to move between virtual +terminals). + +Global keys +=========== + +There are some global keys you can press at any time: + + +==================================== ============================================= +Key Action +==================================== ============================================= +:kbd:`ESC` Go back +:kbd:`F1` Open help menu +:kbd:`Control` + :kbd:`Z`, :kbd:`F2` Switch to shell +:kbd:`Control` + :kbd:`L`, :kbd:`F3` Redraw screen +:kbd:`Control` + :kbd:`T`, :kbd:`F4` Toggle rich mode (colour, Unicode) on and off +==================================== ============================================= diff --git a/doc/howto/autoinstall-quickstart-s390x.rst b/doc/howto/autoinstall-quickstart-s390x.rst new file mode 100644 index 00000000..79829834 --- /dev/null +++ b/doc/howto/autoinstall-quickstart-s390x.rst @@ -0,0 +1,125 @@ +.. _autoinstall-quickstart-s390x: + +Autoinstall quick start for s390x +********************************* + +The intent of this page is to provide simple instructions to perform an +autoinstall in a VM on your machine on s390x. + +This page is just a slightly adapted page of the +`autoinstall quickstart page` mapped to s390x. + +Download an ISO +=============== + +At the time of writing (just after the Kinetic release), the best place to go +is here: +https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/ + +..code-block:: bash + + wget https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/ubuntu-22.10-live-server-s390x.iso -P ~/Downloads + +Mount the ISO +============= + +.. code-block:: bash + + mkdir -p ~/iso + sudo mount -r ~/Downloads/ubuntu-22.10-live-server-s390x.iso ~/iso + +Write your autoinstall config +============================= + +This means creating cloud-init config as follows: + +.. code-block:: bash + + mkdir -p ~/www + cd ~/www + cat > user-data << 'EOF' + #cloud-config + autoinstall: + version: 1 + identity: + hostname: ubuntu-server + password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0" + username: ubuntu + EOF + touch meta-data + +The crypted password is just ``ubuntu``. + +Serve the cloud-init config over HTTP +===================================== + +Leave this running in one terminal window: + +.. code-block:: bash + + cd ~/www + python3 -m http.server 3003 + +Create a target disk +==================== + +Proceed with a second terminal window: + +.. code-block:: bash + + sudo apt install qemu-utils + ... + + qemu-img create -f qcow2 disk-image.qcow2 10G + Formatting 'disk-image.qcow2', fmt=qcow2 size=10737418240 cluster_size=65536 lazy_refcounts=off refcount_bits=16 + + qemu-img info disk-image.qcow2 + image: disk-image.qcow2 + file format: qcow2 + virtual size: 10 GiB (10737418240 bytes) + disk size: 196 KiB + cluster_size: 65536 + Format specific information: + compat: 1.1 + lazy refcounts: false + refcount bits: 16 + corrupt: false + +Run the install! +================ + +.. code-block:: bash + + sudo apt install qemu-kvm + ... + +You may need to add the default user to the ``kvm`` group: <
> + +.. code-block:: bash + + sudo usermod -a -G kvm ubuntu # re-login to make the changes take effect + + kvm -no-reboot -name auto-inst-test -nographic -m 2048 \ + -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio \ + -cdrom ~/Downloads/ubuntu-22.10-live-server-s390x.iso \ + -kernel ~/iso/boot/kernel.ubuntu \ + -initrd ~/iso/boot/initrd.ubuntu \ + -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/ console=ttysclp0' + +This will boot, download the config from the server (set up in the previous +step) and run the install. + +The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means +that ``kvm`` will exit when this happens. It should take about 5 minutes. + +Boot the installed system +========================= + +.. code-block:: bash + + kvm -no-reboot -name auto-inst-test -nographic -m 2048 \ + -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio + +This will boot into the freshly installed system and you should be able to log +in as ``ubuntu/ubuntu``. + diff --git a/doc/howto/autoinstall-quickstart.rst b/doc/howto/autoinstall-quickstart.rst new file mode 100644 index 00000000..56abb7d1 --- /dev/null +++ b/doc/howto/autoinstall-quickstart.rst @@ -0,0 +1,183 @@ +.. _autoinstall_quickstart: + +Autoinstall quick start +*********************** + +The intent of this page is to provide simple instructions to perform an +autoinstall in a VM on your machine. + +This page assumes that you are willing to install the latest Ubuntu release +available i.e., 22.10 at the time of writing. For other releases, you would +need to substitute the name of the ISO image but the instructions should +otherwise remain the same. + +This page also assumes you are on the AMD64 architecture. There is a +:ref:`version for s390x` too. + +Providing the autoinstall data over the network +=============================================== + +This method is the one that generalises most easily to doing an entirely +network-based install, where a machine netboots and then is automatically +installed. + +Download the ISO +---------------- + +Go to the `22.10 ISO download page`_ and download the latest Ubuntu 22.10 +live-server ISO. + +Mount the ISO +------------- + +.. code-block:: bash + + sudo mount -r ~/Downloads/ubuntu-22.10-live-server-amd64.iso /mnt + +Write your autoinstall config +----------------------------- + +This means creating cloud-init config as follows: + +.. code-block:: bash + + mkdir -p ~/www + cd ~/www + cat > user-data << 'EOF' + #cloud-config + autoinstall: + version: 1 + identity: + hostname: ubuntu-server + password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0" + username: ubuntu + EOF + touch meta-data + +The crypted password is just "ubuntu". + +Serve the cloud-init config over HTTP +------------------------------------- + +Leave this running in one terminal window: + +.. code-block:: bash + + cd ~/www + python3 -m http.server 3003 + +Create a target disk +-------------------- + +.. code-block:: + + truncate -s 10G image.img + +Run the install! +---------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio \ + -cdrom ~/Downloads/ubuntu-22.10-live-server-amd64.iso \ + -kernel /mnt/casper/vmlinuz \ + -initrd /mnt/casper/initrd \ + -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/' + +This will boot, download the config from the server (set up in the previous +step) and run the install. The installer reboots at the end but the +``-no-reboot`` flag to ``kvm`` means that ``kvm`` will exit when this happens. +It should take about 5 minutes. + +Boot the installed system +------------------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio + +This will boot into the freshly installed system and you should be able to log +in as ``ubuntu/ubuntu``. + +Using another volume to provide the autoinstall config +====================================================== + +This is the method to use when you want to create media that you can just plug +into a system to have it be installed. + +Download the live-server ISO +---------------------------- + +Go to the `22.10 ISO download page`_ and download the latest Ubuntu 22.10 +live-server ISO. + +Create your user-data and meta-data files +----------------------------------------- + +.. code-block:: bash + + mkdir -p ~/cidata + cd ~/cidata + cat > user-data << 'EOF' + #cloud-config + autoinstall: + version: 1 + identity: + hostname: ubuntu-server + password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0" + username: ubuntu + EOF + touch meta-data + +The crypted password is just ``ubuntu``. + +Create an ISO to use as a cloud-init data source +------------------------------------------------ + +.. code-block:: bash + + sudo apt install cloud-image-utils + cloud-localds ~/seed.iso user-data meta-data + +Create a target disk +-------------------- + +.. code-block:: bash + + truncate -s 10G image.img + +Run the install! +---------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio \ + -drive file=~/seed.iso,format=raw,cache=none,if=virtio \ + -cdrom ~/Downloads/ubuntu-22.10-live-server-amd64.iso + +This will boot and run the install. Unless you interrupt boot to add +'autoinstall' to the kernel command line, the installer will prompt for +confirmation before touching the disk. + +The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means +that ``kvm`` will exit when this happens. + +The whole process should take about 5 minutes. + +Boot the installed system +------------------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio + +This will boot into the freshly installed system and you should be able to log +in as ``ubuntu/ubuntu``. + +.. LINKS + +.. _22.10 ISO download page: https://releases.ubuntu.com/22.10/ \ No newline at end of file diff --git a/doc/howto/index.rst b/doc/howto/index.rst index b3c0b857..f754bfe4 100644 --- a/doc/howto/index.rst +++ b/doc/howto/index.rst @@ -12,8 +12,20 @@ understand and adapt the steps to fit your specific requirements. ----- -How do I...? -============ +Getting started with Autoinstall +================================ .. toctree:: :maxdepth: 1 + + Autoinstall quick-start guide + Autoinstall quick-start guide for s390x + + +Found a problem? +================ + +.. toctree:: + :maxdepth: 1 + + report-bugs diff --git a/doc/howto/report-bugs.rst b/doc/howto/report-bugs.rst new file mode 100644 index 00000000..6bf7fa4d --- /dev/null +++ b/doc/howto/report-bugs.rst @@ -0,0 +1,58 @@ +.. _report-bugs: + +How to report a problem +*********************** + +We always hope, of course, that every install with the server installer +succeeds. But reality doesn't always work that way and there will sometimes be +failures of various kinds. This section explains the most useful way to report +any failures so that we can fix the bugs causing them, and we'll keep the topic +up to date as the installer changes. + +Update Subiquity +================ + +The first thing to do is to update your Subiquity snap. Not only because we +fix issues that cause failures over time but also because we've been working on +features to make failure reporting easier. + + + +Crash reports +============= + +A failure will result in a crash report being generated which bundles up all +the information we need to fully diagnose a failure. These live in +``/var/crash`` in the installer environment, and for Ubuntu 19.10 and newer +this is persisted to the install media by default (if there is space). + +When an error occurs you are presented with a dialog that allows you to upload +the report to the error tracker and offers options for continuing. Uploads to +the error tracker are non-interactive and anonymous, so they are useful for +tracking which kinds of errors are affecting most users, but they do not give +us a way to ask you to help diagnose the failure. + +Create Launchpad bug report +=========================== + +You can create a Launchpad bug report, which lets us establish this kind +of two way communication, based on the contents of a crash report by using the +standard ``apport-cli`` tool that is part of Ubuntu. Copy the crash report to +another system, run: + +.. code-block:: bash + + apport-cli /path/to/report.crash + +and follow the prompts. + +You can also run ``apport-cli`` in the installer environment by switching to a +shell but ``apport`` won't be able to open a browser to allow you to complete +the report so you'll have to type the URL by hand on another machine. + +.. note:: + + Bugs for the Subiquity autoinstaller are `tracked in Launchpad `_. + + + diff --git a/doc/index.rst b/doc/index.rst index 489cbafa..4e194e4d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -76,6 +76,7 @@ constructive feedback. :hidden: :maxdepth: 2 + Introduction to Autoinstall tutorial/index howto/index reference/index diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/intro-to-autoinstall.rst similarity index 100% rename from doc/tutorial/intro-to-autoinstall.rst rename to doc/intro-to-autoinstall.rst diff --git a/doc/reference/autoinstall-reference.rst b/doc/reference/autoinstall-reference.rst index d6ac70cd..b5314bc5 100644 --- a/doc/reference/autoinstall-reference.rst +++ b/doc/reference/autoinstall-reference.rst @@ -3,184 +3,1013 @@ Autoinstall configuration reference manual ****************************************** -.. _ai-active-directory: +The autoinstall file is YAML. At top level it must be a mapping containing the +keys described in this document. Unrecognized keys are ignored. -active-directory -================ +.. _ai-schema: -stub - -.. _ai-apt: - -apt -======= - -stub - -.. _ai-codecs: - -codecs +Schema ====== -stub +Autoinstall configs are +:doc:`validated against a JSON schema` before they are +used. -.. _ai-debconf-selections: +.. _ai-command-lists: -debconf-selections -================== - -stub - -.. _ai-early-commands: - -early-commands -============== - -stub - -.. _ai-error-commands: - -error-commands -============== - -stub - -.. _ai-identity: - -identity -======== - -stub - -.. _ai-interactive-sections: - -interactive-sections -==================== - -stub - -.. _ai-kernel: - -kernel -====== - -stub - -.. _ai-keyboard: - -keyboard -======== - -stub - -.. _ai-late-commands: - -late-commands +Command lists ============= -stub +Several config keys are lists of commands to be executed. Each command can be +a string (in which case it is executed via ``sh -c``) or a list, in which case +it is executed directly. Any command exiting with a non-zero return code is +considered an error and aborts the install (except for error-commands, where +it is ignored). -.. _ai-locale: +.. _ai-top-level-keys: -locale -====== - -stub - -.. _ai-network: - -network -======= - -stub - -.. _ai-oem: - -oem -=== - -stub - -.. _ai-packages: - -packages -======== - -stub - -.. _ai-proxy: - -proxy -===== - -stub - -.. _ai-refresh-installer: - -refresh-installer -================= - -stub - -.. _ai-reporting: - -reporting -========= - -stub - -.. _ai-shutdown: - -shutdown -======== - -stub - -.. _ai-snaps: - -snaps -===== - -stub - -.. _ai-ssh: - -ssh -=== - -stub - -.. _ai-storage: - -storage -======= - -stub - -.. _ai-ubuntu-pro: - -ubuntu-pro -========== - -stub - -.. _ai-updates: - -updates -======= - -stub - -.. _ai-user-data: - -user-data -========= - -stub +Top-level keys +============== .. _ai-version: version -======= +------- -stub +* **type:** integer +* **default:** no default + +A future-proofing config file version field. Currently this must be "1". + +.. _ai-interactive-sections: + +interactive-sections +-------------------- + +* **type:** list of strings +* **default:** [] + +A list of config keys to still show in the UI. So for example: + +.. code-block:: yaml + + version: 1 + interactive-sections: + - network + identity: + username: ubuntu + password: $crypted_pass + +Would stop on the network screen and allow the user to change the defaults. If +a value is provided for an interactive section it is used as the default. + +You can use the special section name of "\*" to indicate that the installer +should ask all the usual questions -- in this case, the :file:`autoinstall.yaml` +file is not really an "autoinstall" file at all, instead just a way to change +the defaults in the UI. + +Not all config keys correspond to screens in the UI. This documentation +indicates if a given section can be interactive or not. + +If there are any interactive sections at all, the :ref:`ai-reporting` key is +ignored. + +.. _ai-early-commands: + +early-commands +-------------- + +* **type:** :ref:`command list` +* **default:** no commands +* **can be interactive:** no + +A list of shell commands to invoke as soon as the installer starts, in +particular before probing for block and network devices. The autoinstall +config is available at :file:`/autoinstall.yaml` (irrespective of how it was +provided) and the file will be re-read after the ``early-commands`` have run to +allow them to alter the config if necessary. + +.. _ai-locale: + +locale +------ + +* **type:** string +* **default:** ``en_US.UTF-8`` +* **can be interactive:** yes, always interactive if any section is + +The locale to configure for the installed system. + +.. _ai-refresh-installer: + +refresh-installer +----------------- + +* **type:** mapping +* **default:** see below +* **can be interactive:** yes + +Controls whether the installer updates to a new version available in the given +channel before continuing. + +The mapping contains keys: + +update +~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to update or not. + +channel +~~~~~~~ + +* **type:** string +* **default:** ``"stable/ubuntu-$REL"`` + +The channel to check for updates. + +.. _ai-keyboard: + +keyboard +-------- + +* **type:** mapping, see below +* **default:** US English keyboard +* **can be interactive:** yes + +The layout of any attached keyboard. Often systems being automatically +installed will not have a keyboard at all in which case the value used here +does not matter. + +The mapping's keys correspond to settings in the :file:`/etc/default/keyboard` +configuration file. See +`its manual page `_ +for more details. + +The mapping contains keys: + +layout +~~~~~~ + +* **type:** string +* **default:** ``"us"`` + +Corresponds to the ``XKBLAYOUT`` setting. + +variant +~~~~~~~ + +* **type:** string +* **default:** ``""`` + +Corresponds to the ``XKBVARIANT`` setting. + +toggle +~~~~~~ + +* **type:** string or null +* **default:** ``null`` + +Corresponds to the value of ``grp:`` option from the ``XKBOPTIONS`` setting. +Acceptable values are (but note that the installer does not validate these): +``caps_toggle``, ``toggle``, ``rctrl_toggle``, ``rshift_toggle``, +``rwin_toggle``, ``menu_toggle``, ``alt_shift_toggle``, ``ctrl_shift_toggle``, +``ctrl_alt_toggle``, ``alt_caps_toggle``, ``lctrl_lshift_toggle``, +``lalt_toggle``, ``lctrl_toggle``, ``lshift_toggle``, ``lwin_toggle``, +``sclk_toggle`` + +The version of Subiquity released with 20.04 GA does not accept ``null`` for +this field due to a bug. + +.. _ai-source: + +source +------ + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +search_drivers +~~~~~~~~~~~~~~ + +* **type:** boolean +* **default:** ``true`` + +Whether the installer should search for available third-party drivers. When +set to ``false``, it disables the drivers :ref:`screen and section`. + +id +~~ + +* **type:** string +* **default:** identifier of the first available source. + +Identifier of the source to install (e.g., ``"ubuntu-server-minimal"``). + +.. _ai-network: + +network +------- + +* **type:** netplan-format mapping, see below +* **default:** DHCP on interfaces named ``eth*`` or ``en*`` +* **can be interactive:** yes + +`Netplan-formatted `_ network configuration. +This will be applied during installation as well as in the installed system. +The default is to interpret the config for the install media, which runs +DHCPv4 on any interface with a name matching "``eth*``" or "``en*``" but then +disables any interface that does not receive an address. + +For example, to run DHCPv6 on a particular NIC: + +.. code-block:: yaml + + network: + version: 2 + ethernets: + enp0s31f6: + dhcp6: true + +Note that because of a bug, the version of Subiquity released with 20.04 GA +forces you to write this with an extra ``network:`` key like so: + +.. code-block:: yaml + + network: + network: + version: 2 + ethernets: + enp0s31f6: + dhcp6: true + +Later versions support this syntax too for compatibility but if you can +assume a newer version you should use the former. + +.. _ai-proxy: + +proxy +----- + +* **type:** URL or ``null`` +* **default:** no proxy +* **can be interactive:** yes + +The proxy to configure both during installation and for ``apt`` and for +``snapd`` in the target system. + +.. _ai-apt: + +apt +--- + +* **type:** mapping +* **default:** see below +* **can be interactive:** yes + +APT configuration, used both during the install and once booted into the target +system. + +This section historically used the same format as curtin, +`which is documented here `_. +Nonetheless, some key differences with the format supported by curtin have been introduced: + +- Subiquity supports an alternative format for the ``primary`` section, + allowing configuration of a list of candidate primary mirrors. During + installation, Subiquity will automatically test the specified mirrors and + select the first one that seems usable. This new behavior is only activated + when the ``primary`` section is wrapped in the ``mirror-selection`` section. + +- The ``fallback`` key controls what Subiquity should do if no primary mirror + is usable. + +- The ``geoip`` key controls whether a geoip lookup is done to determine the + correct country mirror. + +The default is: + +.. code-block:: yaml + + apt: + preserve_sources_list: false + mirror-selection: + primary: + - country-mirror + - arches: [i386, amd64] + uri: "http://archive.ubuntu.com/ubuntu" + - arches: [s390x, arm64, armhf, powerpc, ppc64el, riscv64] + uri: "http://ports.ubuntu.com/ubuntu-ports" + fallback: abort + geoip: true + + +mirror-selection +~~~~~~~~~~~~~~~~ + +if the ``primary`` section is contained within the ``mirror-selection`` +section, the automatic mirror selection is enabled. This is the default in new installations. + +primary (when placed inside the ``mirror-selection`` section): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* **type:** custom, see below + +In the new format, the ``primary`` section expects a list of mirrors, which +can be expressed in two different ways: + +* The special value ``country-mirror`` +* A mapping with the following keys: + + * ``uri``: The URI of the mirror to use, e.g., "http://fr.archive.ubuntu.com/ubuntu" + * ``arches``: An optional list of architectures supported by the mirror. By + default, this list contains the current CPU architecture. + +fallback +~~~~~~~~ + +* **type:** string (enumeration) +* **default:** abort + +Controls what Subiquity should do if no primary mirror is usable. Supported +values are: + +* ``abort`` -> abort the installation +* ``offline-install`` -> revert to an offline installation +* ``continue-anyway`` -> attempt to install the system anyway (not recommended, + the installation will certainly fail) + +geoip +~~~~~ + +* **type:** boolean +* **default:** ``true`` + +If geoip is true and one of the candidate primary mirrors has the special +value ``country-mirror``, a request is made to ``https://geoip.ubuntu.com/lookup``. +Subiquity then sets the mirror URI to ``http://CC.archive.ubuntu.com/ubuntu`` +(or similar for ports) where ``CC`` is the country code returned by the lookup. +If this section is not interactive, the request is timed out after 10 seconds. + +If the legacy behavior (i.e., without mirror-selection) is in use, the geoip +request is made if the mirror to be used is the default, and its URI ends up +getting replaced by the proper country mirror URI. + +If you just want to specify a mirror, you can use a configuration like this: + +.. code-block:: yaml + + apt: + mirror-selection: + primary: + - uri: YOUR_MIRROR_GOES_HERE + - country-mirror + - uri: http://archive.ubuntu.com/ubuntu + +To add a ppa: + +.. code-block:: yaml + + apt: + sources: + curtin-ppa: + source: ppa:curtin-dev/test-archive + +.. _ai-storage: + +storage +------- + +* **type:** mapping, see below +* **default:** use "lvm" layout in a single disk system, no default in a + multiple disk system +* **can be interactive:** yes + +Storage configuration is a complex topic and the description of the desired +configuration in the autoinstall file can also be complex. The installer +supports "layouts"; simple ways of expressing common configurations. + +Supported layouts +~~~~~~~~~~~~~~~~~ + +The three supported layouts at the time of writing are "lvm", "direct", and "zfs". + +.. code-block:: yaml + + storage: + layout: + name: lvm + storage: + layout: + name: direct + storage: + layout: + name: zfs + + +By default these will install to the largest disk in a system, but you can +supply a match spec (see below) to indicate which disk to use: + +.. code-block:: yaml + + storage: + layout: + name: lvm + match: + serial: CT* + storage: + layout: + name: direct + match: + ssd: true + +.. note:: + Match spec -- using "``match: {}``" will match an arbitrary disk + +When using the "lvm" layout, LUKS encryption can be enabled by supplying a +password. + +.. code-block:: yaml + + storage: + layout: + name: lvm + password: LUKS_PASSPHRASE + + +The default is to use the ``lvm`` layout. + +Sizing-policy +~~~~~~~~~~~~~ + +The lvm layout will, by default, attempt to leave room for snapshots and +further expansion. A sizing-policy key may be supplied to control this +behavior. + +* **type:** string (enumeration) +* **default:** scaled + +Supported values are: + +* ``scaled`` -> adjust space allocated to the root LV based on space available + to the VG +* ``all`` -> allocate all remaining VG space to the root LV + +The scaling system is currently as follows: + +* Less than 10 GiB: use all remaining space for root filesystem +* Between 10--20 GiB: 10 GiB root filesystem +* Between 20--200 GiB: use half of remaining space for root filesystem +* Greater than 200 GiB: 100 GiB root filesystem + +Example with no size scaling and a passphrase: + +.. code-block:: yaml + + storage: + layout: + name: lvm + sizing-policy: all + password: LUKS_PASSPHRASE + +Action-based config +~~~~~~~~~~~~~~~~~~~ + +For full flexibility, the installer allows storage configuration to be done +using a syntax which is a superset of that supported by curtin, as described in +`the curtin documentation `_. + +If the "layout" feature is used to configure the disks, the "config" section +will not be used. + +As well as putting the list of actions under the 'config' key, the +`grub `_ and +`swap `_ +curtin config items can be put here. So a storage section might look like: + +.. code-block:: yaml + + storage: + swap: + size: 0 + config: + - type: disk + id: disk0 + serial: ADATA_SX8200PNP_XXXXXXXXXXX + - type: partition + ... + + +The extensions to the curtin syntax are around disk selection and +partition/logical volume sizing. + +Disk selection extensions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Curtin supported identifying disks by serial (e.g. +``Crucial_CT512MX100SSD1_14250C57FECE``) or by path (e.g. ``/dev/sdc``) and the +server installer supports this as well. The installer additionally supports a +''match spec'' on a disk action that supports more flexible matching. + +The actions in the storage config are processed in the order they are in the +autoinstall file. Any disk action is assigned a matching disk -- chosen +arbitrarily from the set of unassigned disks if there is more than one, and +causing the installation to fail if there is no unassigned matching disk. + +A match spec supports the following keys: + +* ``model: foo``: matches a disk where ``ID_VENDOR=foo`` in udev, supporting + globbing +* ``path: foo``: matches a disk based on path (e.g. ``/dev/sdc``), supporting + globbing (the globbing support distinguishes this from specifying path: foo + directly in the disk action) +* ``id_path: foo``: matches a disk where ``ID_PATH=foo`` in udev, supporting + globbing +* ``devpath: foo``: matches a disk where ``DEVPATH=foo`` in udev, supporting + globbing +* ``serial: foo``: matches a disk where ``ID_SERIAL=foo`` in udev, supporting + globbing (the globbing support distinguishes this from specifying serial: foo + directly in the disk action) +* ``ssd: true|false``: matches a disk that is or is not an SSD (vs. a rotating + drive) +* ``size: largest|smallest``: take the largest or smallest disk rather than an + arbitrary one if there are multiple matches (support for ``smallest`` added + in version 20.06.1) + +A special sort of key is ``install-media: true``, which will take the disk the +installer was loaded from (the ``ssd`` and ``size`` selectors will never return +this disk). If installing to the install media, care obviously needs to be taken +to not overwrite the installer itself! + +So for example, to match an arbitrary disk it is simply: + +.. code-block:: yaml + + - type: disk + id: disk0 + +To match the largest SSD: + +.. code-block:: yaml + + - type: disk + id: big-fast-disk + match: + ssd: true + size: largest + +To match a Seagate drive: + +.. code-block:: yaml + + - type: disk + id: data-disk + match: + model: Seagate + + +Partition/logical volume extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The size of a partition or logical volume in curtin is specified as a number of +bytes. The autoinstall config is more flexible: + +* You can specify the size using the "1G", "512M" syntax supported in the + installer UI. +* You can specify the size as a percentage of the containing disk (or RAID), + e.g. "50%". +* For the last partition specified for a particular device, you can specify + the size as "-1" to indicate that the partition should fill the remaining + space. + +.. code-block:: yaml + + - type: partition + id: boot-partition + device: root-disk + size: 10% + - type: partition + id: root-partition + size: 20G + - type: partition + id: data-partition + device: root-disk + size: -1 + +.. _ai-identity: + +identity +-------- + +* **type:** mapping, see below +* **default:** no default +* **can be interactive:** yes + +Configure the initial user for the system. This is the only config key that +must be present (unless the :ref:`user-data section ` is present, +in which case it is optional). + +A mapping that can contain keys, all of which take string values: + +realname +~~~~~~~~ + +The real name for the user. This field is optional. + +username +~~~~~~~~ + +The user name to create. + +hostname +~~~~~~~~ + +The hostname for the system. + +password +~~~~~~~~ + +The password for the new user, encrypted. This is required for use with +``sudo``, even if SSH access is configured. + +The crypted password string must conform to what +`passwd `_ +expects. Depending on the special characters in the password hash, quoting may +be required, so it's safest to just always include the quotes around the hash. + +Several tools can generate the crypted password, such as ``mkpasswd`` from the +``whois`` package, or ``openssl passwd``. + +Example: + +.. code-block:: yaml + + identity: + realname: 'Ubuntu User' + username: ubuntu + password: '$6$wdAcoXrU039hKYPd$508Qvbe7ObUnxoj15DRCkzC3qO7edjH0VV7BPNRDYK4QR8ofJaEEF2heacn0QgD.f8pO8SNp83XNdWG6tocBM1' + hostname: ubuntu + +.. _ai-active-directory: + +active-directory +---------------- + +* **type:** mapping, see below +* **default:** no default +* **can be interactive:** yes + +Accepts data required to join the target system in an Active Directory domain. + +A mapping that can contain keys, all of which take string values: + +admin-name +~~~~~~~~~~ + +A domain account name with privilege to perform the join operation. That +account's password will be requested during runtime. + +domain-name +~~~~~~~~~~~ + +The Active Directory domain to join. + +.. _ai-ubuntu-pro: + +ubuntu-pro +---------- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +token +~~~~~ + +* **type:** string +* **default:** no token + +A contract token to attach to an existing Ubuntu Pro subscription. + +.. _ai-ssh: + +ssh +--- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +Configure SSH for the installed system. A mapping that can contain keys: + +install-server +~~~~~~~~~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to install OpenSSH server in the target system. + +authorized-keys +~~~~~~~~~~~~~~~ + +* **type:** list of strings +* **default:** ``[]`` + +A list of SSH public keys to install in the initial user's account. + +allow-pw +~~~~~~~~ + +* **type:** boolean +* **default:** ``true`` if ``authorized_keys`` is empty, ``false`` otherwise + +.. _ai-codecs: + +codecs +------ + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** no + +Configure whether common restricted packages (including codecs) from +[multiverse] should be installed. + +install +~~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to install the ubuntu-restricted-addons package. + +.. _ai-drivers: + +drivers +------- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +install +~~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to install the available third-party drivers. + +.. _ai-oem: + +oem +--- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** no + +install +~~~~~~~ + +* **type:** boolean or string (special value ``auto``) +* **default:**: ``auto`` + +Whether to install the available OEM meta-packages. The special value ``auto`` +-- which is the default -- enables the installation on ubuntu-desktop but not +on ubuntu-server. This option has no effect on core boot classic. + +.. _ai-snaps: + +snaps +----- + +* **type:** list +* **default:** install no extra snaps +* **can be interactive:** yes + +A list of snaps to install. Each snap is represented as a mapping with required +``name`` and optional ``channel`` (defaulting to ``stable``) and classic +(defaulting to ``false``) keys. For example: + +.. code-block: yaml + + snaps: + - name: etcd + channel: edge + classic: false + +.. _ai-debconf-selections: + +debconf-selections +------------------ + +* **type:** string +* **default:** no config +* **can be interactive:** no + +The installer will update the target with debconf set-selection values. Users +will need to be familiar with the package debconf options. + +.. _ai-packages: + +packages +-------- + +* **type:** list +* **default:** no packages +* **can be interactive:** no + +A list of packages to install into the target system. More precisely, a list of +strings to pass to "``apt-get install``", so this includes things like task +selection (``dns-server^``) and installing particular versions of a package +(``my-package=1-1``). + +.. _ai-kernel: + +kernel +------ + +* **type:** mapping (mutually exclusive), see below +* **default:** default kernel +* **can be interactive:** no + +Which kernel gets installed. Either the name of the package or the name of the +flavor must be specified. + +package +~~~~~~~ + +**type:** string + +The name of the package, e.g., ``linux-image-5.13.0-40-generic`` + +flavor +~~~~~~ + +* **type:** string + +The flavor of the kernel, e.g., ``generic`` or ``hwe``. + +.. _ai-timezone: + +timezone +-------- + +* **type:** string +* **default:** no timezone +* **can be interactive:** no + +The timezone to configure on the system. The special value "geoip" can be used +to query the timezone automatically over the network. + +.. _ai-updates: + +updates +------- + +* **type:** string (enumeration) +* **default:** ``security`` +* **can be interactive:** no + +The type of updates that will be downloaded and installed after the system +install. Supported values are: + +* ``security`` -> download and install updates from the -security pocket +* ``all`` -> also download and install updates from the -updates pocket + +.. _ai-shutdown: + +shutdown +-------- + +* **type:** string (enumeration) +* **default:** ``reboot`` +* **can be interactive:** no + +Request the system to power off or reboot automatically after the installation +has finished. Supported values are: + +* ``reboot`` +* ``poweroff`` + +.. _ai-late-commands: + +late-commands +------------- + +* **type:** :ref:`command list` +* **default:** no commands +* **can be interactive:** no + +Shell commands to run after the install has completed successfully and any +updates and packages installed, just before the system reboots. They are run in +the installer environment with the installed system mounted at ``/target``. You +can run ``curtin in-target -- $shell_command`` (with the version of Subiquity +released with 20.04 GA you need to specify this as +``curtin in-target --target=/target -- $shell_command``) to run in the target +system (similar to how plain ``in-target`` can be used in +``d-i preseed/late_command``). + +.. _ai-error-commands: + +error-commands +-------------- + +* **type:** :ref:`command list` +* **default:** no commands +* **can be interactive:** no + +Shell commands to run after the install has failed. They are run in the +installer environment, and the target system (or as much of it as the installer +managed to configure) will be mounted at ``/target``. Logs will be available +at :file:`/var/log/installer` in the live session. + +.. _ai-reporting: + +reporting +--------- + +* **type:** mapping +* **default:** ``type: print`` which causes output on tty1 and any configured + serial consoles +* **can be interactive:** no + +The installer supports reporting progress to a variety of destinations. Note +that this section is ignored if there are any :ref:`interactive sections `; it only applies to fully automated installs. + +The config, and indeed the implementation, is 90% the same as +`that used by curtin `_. + +Each key in the ``reporting`` mapping in the config defines a destination, +where the ``type`` sub-key is one of: + +**The rsyslog reporter does not yet exist** + +* **print**: print progress information on tty1 and any configured serial + console. There is no other configuration. +* **rsyslog**: report progress via rsyslog. The **destination** key specifies + where to send output. +* **webhook**: report progress via POSTing JSON reports to a URL. Accepts the + same `configuration as curtin `_. +* **none**: do not report progress. Only useful to inhibit the default output. + +Examples: + +The default configuration is: + +.. code-block:: yaml + + reporting: + builtin: + type: print + +Report to rsyslog: + +.. code-block:: yaml + + reporting: + central: + type: rsyslog + destination: @192.168.0.1 + + +Suppress the default output: + +.. code-block:: yaml + + reporting: + builtin: + type: none + +Report to a curtin-style webhook: + +.. code-block:: yaml + + reporting: + hook: + type: webhook + endpoint: http://example.com/endpoint/path + consumer_key: "ck_foo" + consumer_secret: "cs_foo" + token_key: "tk_foo" + token_secret: "tk_secret" + level: INFO + + +.. _ai-user-data: + +user-data +--------- + +* **type:** mapping +* **default:** ``{}`` +* **can be interactive:** no + +Provide cloud-init user data which will be merged with the user data the +installer produces. If you supply this, you don't need to supply an +:ref:`identity section ` (but then it's your responsibility to +make sure that you can log into the installed system!). diff --git a/doc/reference/autoinstall-schema.rst b/doc/reference/autoinstall-schema.rst new file mode 100644 index 00000000..1b8bf0a9 --- /dev/null +++ b/doc/reference/autoinstall-schema.rst @@ -0,0 +1,589 @@ +.. _autoinstall_schema: + +Autoinstall schema +****************** + +The server installer validates the provided autoinstall config against a +:ref:`JSON schema`. + +How the config is validated +=========================== + +Although the schema is presented below as a single document, and if you want +to pre-validate your config you should validate it against this document, the +config is not actually validated against this document at run time. What +happens instead is that some sections are loaded, validated, and applied +first, before all other sections are validated. In detail: + +1. The reporting section is loaded, validated and applied. +2. The error commands are loaded and validated. +3. The early commands are loaded and validated. +4. The early commands, if any, are run. +5. The config is reloaded, and now all sections are loaded and validated. + +This is so that validation errors in most sections can be reported via the +reporting and error-commands configuration, as all other errors are. + +.. _autoinstall_JSON_schema: + +Schema +====== + +The `JSON schema`_ for autoinstall data is as follows: + +.. code-block:: JSON + + "type": "object", + "properties": { + "version": { + "type": "integer", + "minimum": 1, + "maximum": 1 + }, + "early-commands": { + "type": "array", + "items": { + "type": [ + "string", + "array" + ], + "items": { + "type": "string" + } + } + }, + "reporting": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "type": { + "type": "string" + } + }, + "required": [ + "type" + ], + "additionalProperties": true + } + }, + "error-commands": { + "type": "array", + "items": { + "type": [ + "string", + "array" + ], + "items": { + "type": "string" + } + } + }, + "user-data": { + "type": "object" + }, + "packages": { + "type": "array", + "items": { + "type": "string" + } + }, + "debconf-selections": { + "type": "string" + }, + "locale": { + "type": "string" + }, + "refresh-installer": { + "type": "object", + "properties": { + "update": { + "type": "boolean" + }, + "channel": { + "type": "string" + } + }, + "additionalProperties": false + }, + "kernel": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "flavor": { + "type": "string" + } + }, + "oneOf": [ + { + "type": "object", + "required": [ + "package" + ] + }, + { + "type": "object", + "required": [ + "flavor" + ] + } + ] + }, + "keyboard": { + "type": "object", + "properties": { + "layout": { + "type": "string" + }, + "variant": { + "type": "string" + }, + "toggle": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "layout" + ], + "additionalProperties": false + }, + "source": { + "type": "object", + "properties": { + "search_drivers": { + "type": "boolean" + }, + "id": { + "type": "string" + } + } + }, + "network": { + "oneOf": [ + { + "type": "object", + "properties": { + "version": { + "type": "integer", + "minimum": 2, + "maximum": 2 + }, + "ethernets": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "wifis": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "bridges": { + "type": "object" + }, + "bonds": { + "type": "object" + }, + "tunnels": { + "type": "object" + }, + "vlans": { + "type": "object" + } + }, + "required": [ + "version" + ] + }, + { + "type": "object", + "properties": { + "network": { + "type": "object", + "properties": { + "version": { + "type": "integer", + "minimum": 2, + "maximum": 2 + }, + "ethernets": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "wifis": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "bridges": { + "type": "object" + }, + "bonds": { + "type": "object" + }, + "tunnels": { + "type": "object" + }, + "vlans": { + "type": "object" + } + }, + "required": [ + "version" + ] + } + }, + "required": [ + "network" + ] + } + ] + }, + "ubuntu-pro": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 24, + "maxLength": 30, + "pattern": "^C[1-9A-HJ-NP-Za-km-z]+$", + "description": "A valid token starts with a C and is followed by 23 to 29 Base58 characters.\nSee https://pkg.go.dev/github.com/btcsuite/btcutil/base58#CheckEncode" + } + } + }, + "ubuntu-advantage": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 24, + "maxLength": 30, + "pattern": "^C[1-9A-HJ-NP-Za-km-z]+$", + "description": "A valid token starts with a C and is followed by 23 to 29 Base58 characters.\nSee https://pkg.go.dev/github.com/btcsuite/btcutil/base58#CheckEncode" + } + }, + "deprecated": true, + "description": "Compatibility only - use ubuntu-pro instead" + }, + "proxy": { + "type": [ + "string", + "null" + ], + "format": "uri" + }, + "apt": { + "type": "object", + "properties": { + "preserve_sources_list": { + "type": "boolean" + }, + "primary": { + "type": "array" + }, + "mirror-selection": { + "type": "object", + "properties": { + "primary": { + "type": "array", + "items": { + "anyOf": [ + { + "type": "string", + "const": "country-mirror" + }, + { + "type": "object", + "properties": { + "uri": { + "type": "string" + }, + "arches": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "uri" + ] + } + ] + } + } + } + }, + "geoip": { + "type": "boolean" + }, + "sources": { + "type": "object" + }, + "disable_components": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "universe", + "multiverse", + "restricted", + "contrib", + "non-free" + ] + } + }, + "preferences": { + "type": "array", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "pin": { + "type": "string" + }, + "pin-priority": { + "type": "integer" + } + }, + "required": [ + "package", + "pin", + "pin-priority" + ] + } + }, + "fallback": { + "type": "string", + "enum": [ + "abort", + "continue-anyway", + "offline-install" + ] + } + } + }, + "storage": { + "type": "object" + }, + "identity": { + "type": "object", + "properties": { + "realname": { + "type": "string" + }, + "username": { + "type": "string" + }, + "hostname": { + "type": "string" + }, + "password": { + "type": "string" + } + }, + "required": [ + "username", + "hostname", + "password" + ], + "additionalProperties": false + }, + "ssh": { + "type": "object", + "properties": { + "install-server": { + "type": "boolean" + }, + "authorized-keys": { + "type": "array", + "items": { + "type": "string" + } + }, + "allow-pw": { + "type": "boolean" + } + } + }, + "snaps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "channel": { + "type": "string" + }, + "classic": { + "type": "boolean" + } + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "active-directory": { + "type": "object", + "properties": { + "admin-name": { + "type": "string" + }, + "domain-name": { + "type": "string" + } + }, + "additionalProperties": false + }, + "codecs": { + "type": "object", + "properties": { + "install": { + "type": "boolean" + } + } + }, + "drivers": { + "type": "object", + "properties": { + "install": { + "type": "boolean" + } + } + }, + "oem": { + "type": "object", + "properties": { + "install": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "auto" + } + ] + } + }, + "required": [ + "install" + ] + }, + "timezone": { + "type": "string" + }, + "updates": { + "type": "string", + "enum": [ + "security", + "all" + ] + }, + "late-commands": { + "type": "array", + "items": { + "type": [ + "string", + "array" + ], + "items": { + "type": "string" + } + } + }, + "shutdown": { + "type": "string", + "enum": [ + "reboot", + "poweroff" + ] + } + }, + "required": [ + "version" + ], + "additionalProperties": true + } + +Regeneration +============ + +The schema above can be regenerated by running ``make schema`` in a Subiquity +source checkout. + +.. LINKS + +.. _JSON schema: https://json-schema.org/ diff --git a/doc/reference/index.rst b/doc/reference/index.rst index ab5afb94..fc2a0d87 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -5,16 +5,13 @@ Our reference section contains support information for Subiquity. This includes details on the network requirements, API definitions, support matrices and so on. +----- + Autoinstall reference manual ============================ - .. toctree:: :maxdepth: 1 - autoinstall-reference.rst - ------ - -.. toctree:: - :maxdepth: 1 + Autoinstall configuration + Autoinstall JSON schema diff --git a/doc/tutorial/basic-server-installation.rst b/doc/tutorial/basic-server-installation.rst new file mode 100644 index 00000000..19c657c3 --- /dev/null +++ b/doc/tutorial/basic-server-installation.rst @@ -0,0 +1,123 @@ +Basic server installation +************************* + +This chapter provides an overview of how to install Ubuntu Server Edition. You +can also refer to this guide on +:ref:`how to operate the installer ` for more +information on using the installer, and to this +:doc:`screen-by-screen reference guide ` for more +information about each of the installer screens. + +Preparing to install +==================== + +This section explains various aspects to consider before starting the +installation. + +System requirements +------------------- + +Ubuntu Server Edition provides a common, minimalist base for a variety of +server applications, such as file/print services, web hosting, email hosting, +etc. This version supports four 64-bit architectures: + +* amd64 (Intel/AMD 64-bit) +* arm64 (64-bit ARM) +* ppc64el (POWER8 and POWER9) +* s390x (IBM Z and LinuxONE) + +The recommended system requirements are: + +* CPU: 1 gigahertz or better +* RAM: 1 gigabyte or more +* Disk: a minimum of 2.5 gigabytes + +Perform a system back up +------------------------ + +Before installing Ubuntu Server Edition you should make sure all data on the +system is backed up. + +If this is not the first time an operating system has been installed on your +computer, it is likely you will need to re-partition your disk to make room +for Ubuntu. + +Any time you partition your disk, you should be prepared to lose everything on +the disk should you make a mistake or something goes wrong during partitioning. +The programs used in installation are quite reliable, most have seen years of +use, but they also perform destructive actions. + +Download the server ISO +----------------------- + +You can obtain the amd64 server download from https://releases.ubuntu.com/. +Select the version you wish to install and select the "server install image" +download. Note that the server download includes the installer. + +There are platform-specific how-to guides for installations on: + +* `s390x LPAR `_ +* `z/VM `_ +* `ppc64el `_ + +Create a bootable USB +--------------------- + +There are many ways to boot the installer but the simplest and most common way +is to +`create a bootable USB stick `_ +to boot the system to be installed with +(`tutorials for other operating systems `_ +are also available). + +Perform the installation +======================== + +Now that you have prepared your install medium, you are ready to install. + +Boot the installer +------------------ + +Plug the USB stick into the system to be installed and start it. + +Most computers will automatically boot from USB or DVD, though in some cases +this is disabled to improve boot times. If you don't see the boot message and +the "Welcome" screen which should appear after it, you will need to set your +computer to boot from the install media. + +There should be an on-screen message when the computer starts, telling you what +key to press for settings or a boot menu. Depending on the manufacturer, this +could be :kbd:`Escape`, :kbd:`F2`, :kbd:`F10` or :kbd:`F12`. Restart your +computer and hold down this key until the boot menu appears, then select the +drive with the Ubuntu install media. + +If you are still having problems, check out the +`Ubuntu Community documentation on booting from +CD/DVD `_. + +After a few moments, the installer will start in its language selection screen. + +.. image:: figures/basic-installation-start-screen.png + :alt: Welcome screen of the Server installer showing the language selection options + +Using the installer +------------------- + +The installer is designed to be easy to use and have sensible defaults so for +a first install you can mostly just accept the defaults for the most +straightforward install: + +* Choose your language +* Update the installer (if offered) +* Select your keyboard layout +* Do not configure networking (the installer attempts to configure wired + network interfaces via DHCP, but you can continue without networking if this + fails) +* Do not configure a proxy or custom mirror unless you have to in your network +* For storage, leave "use an entire disk" checked, and choose a disk to install + to, then select "Done" on the configuration screen and confirm the install +* Enter a username, hostname and password +* On the SSH and snap screens, select "Done" +* You will now see log messages as the install is completed +* Select restart when this is complete, and log in using the username and + password provided diff --git a/doc/tutorial/figures/basic-installation-start-screen.png b/doc/tutorial/figures/basic-installation-start-screen.png new file mode 100644 index 0000000000000000000000000000000000000000..845d68d23012e4e7a8b69da7e15d7b8dd3ad9bb5 GIT binary patch literal 3438 zcmds(>08oU*T>1~2x5w6TBhmGG}ChGWaWebnwX}Rb5`b5IctyLj2^|QEGfs#Ay1At z9XX-_4wY!AmE|lrlw(5XK~n@nZ_fQ(&p+|3{bF5fU)S2}#rLz$B|sq1 z0c*6yH4td8DhMRzwr{WK=AK(AO5~&+Y@IA+WMr0|RCjlGrSPhI_UwU6-`OKdQM9%| zI7Km6iUaR+>SRG$*hCk7#Z}emx2?N|Q!1wWo)*2MWEf^rYp*paPdpe-J@Q8)O!T72 zrftO>RrdjjFgyqe69Xf_qF|^=ZN7A%TcwC*d7$Ld%>>Sju!W#eVJJEpyQe+TZcd$m z?+V;xVF0H^R{AN}JyeJD>~D;Zh8sOzuumB-PCzkQABUOozbhc~e%L?|7cZi z2`!}sXAf*`9TCQ|HicN$-OBa&;CKIcAena?Sq~GA`?^~JHpUXm_V>5tA8X!AAhGZA zG*_J%F`GL-)awGbD|h%a{pHn`LXO_TbrR_smY`b~(nxy+h% zF1h4KpmoAkzluP-k`II69&e8pq!My^+_==fzD`ew5zAEtHRy|!Ld5e;Q@524h@d0shdyl-^hE4)e5^DIJjZDqQjE*51P2- zOcvJL$I^C>FH?n{M6KnROkk=bmA7+;SxeoCW(L046UcuTSZ`Bkm)99$j9^GVpS*{w z;w!_FU>Cti5Rgc4$Nw)TAkga(aMhRm3|h7#icn28bA=!bJ8^QV(MNOF;E#waLTb@!zO>KqeXZ*b~0DjU*mT+cA6F+x=U*why=>>|EVF22Omdx*Py(?z;3Xf zg;c4^tV2>ChlM5Mi*Pb*Z1l|3IRgv5igKmlsHcL%gTCm4vYWEb=K*1>sg&lqA~3`R z`09in$Kzk_OF$+qzMg~{ACfJ1ao@gnXl*6{@CFppuXrDTJw2)cC#zlrX6Fl%^YM=+lS*@g}mj)Rj3t3&^1p} zXy(daxxmf0`5M|;wM)x?i2Ogn{`FBGh9IIpjSNwj^@bmF zghb<_Aw9e&5 z!M{sembl8* zE&t$kt!f;cMrnYp9RrBbx^?3N>gs7meuqj2KA&@U08`dy)i7m*O_lsvm33+d7hs zJFcxtee8hkUeUx@;&D2#A?Msz^0I;*0`sw-NBZgx;a54C_K+Xb-wD&CNOM zl$v~~CcRpmi>o-c@kvh>b(R(TEg>#Fg2!!%jq47|UBF#HMmk~+$$CqIDRp?fLt0BN z?#XqJtA01NeLYs(gY#iLgiw`^l@!$--56`dJ^51{7?YR~SYB5=4K^5w@NP@|q#_0a zg((g%3`JzV*y(8Ih0VTmxkZ~O=;y$UWMqS&+^GmPzuCmN>>KIfM~}B3STqaqcc@)L4kT zK5-1mV{{53I0&6{e%>_s z)>29RK)hT8ty%Z$y`cUkz~ljsPhyI7Pr1P+7RwNfZ5uRL7)1zCmZ?Ryxw?DZOOp*jQQ_$#T zsDEHufx>KOpW>KQlP*2hK_%s9yjppCetG*`A-jw22d2!w4RdpB_b}fFU<>UkUpZ9O zf5%r?eP zK=1ijW{&OeII2*g(`4K|PGC~MxT57C#RUB~@$EY))gee`A=}A4fByyv%+&7oP=zZub-nd?DB*3*g&@ zK2N+${a1BUicWrh&Ahd5W)0^^}k)^OB2YAw;DuIg6R$hS0&zikRb+e^^UFJYYzr!GYP76Mhb163rrQj zM$Q#q+BFTJ{Qda>Z0ym)@XkEJ2_ifzy5~UCar#CWUbX8jy(ym0oYZV;F;<&bM%<)g zhFb-c(rxwMGJ+prh;`>BAOaG;fJnL_zM-E9neaycbrcm>)m}_E_h?0#9v(^Ib zit8T;;|%0&{?=uheCiu>&|)G8z^I-f~)|z<`GW#a-_@pNI>~U+F^xR)9Og%VmdHAG(9!` zHl0wLlEYOU6rduWRz?d@b^CcD3{LpK=MX{rF^m1wlPks1vo=edwD)s}BB+178pYg# zoi#e@#C&w34 zqU>Y)slZeetf^DKAQV6`Juc0w%}+^Q(L6IJv$Z1aH3b6|kOhTN8~3ab?KU?SGc<2) zqvqH9y#}XGHK1ABV1sb4@xhzRp%7VoTW(hjd+2LS9JtkG@9UhVlD>Wm zhtjL*V;iVN9a$ORoN2lbP>e<1`X zZIEXGU`CG^O&(Bzt=$1+sYZ5dF>HgJkEbAuOmdv7d-T?uUZ;cw^1aa8)vGT`#>As_ z=(i=qi#HeBS~DS9f%wc~=Y>XabT+Ks+0os+{b#NCNN|#EEriE+F3LpZzuf+6FN=$ literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-complete.png b/doc/tutorial/figures/sbs-complete.png new file mode 100644 index 0000000000000000000000000000000000000000..12577b331e9b04e03a3189bc19d75b76be49d037 GIT binary patch literal 6803 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 literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-confirm-storage.png b/doc/tutorial/figures/sbs-confirm-storage.png new file mode 100644 index 0000000000000000000000000000000000000000..8eb6cec66ebfbbe149860a9c4949230b3ac256fe GIT binary patch literal 3801 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 literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-identity.png b/doc/tutorial/figures/sbs-identity.png new file mode 100644 index 0000000000000000000000000000000000000000..40d85c8b47ae93c05a01304fe182321792948b58 GIT binary patch literal 2484 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 G)c*ht#!hbl literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-language.png b/doc/tutorial/figures/sbs-language.png new file mode 100644 index 0000000000000000000000000000000000000000..845d68d23012e4e7a8b69da7e15d7b8dd3ad9bb5 GIT binary patch literal 3438 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 literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-logs.png b/doc/tutorial/figures/sbs-logs.png new file mode 100644 index 0000000000000000000000000000000000000000..a19fc5301edb0243342102187561283731307649 GIT binary patch literal 4731 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 literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-proxy.png b/doc/tutorial/figures/sbs-proxy.png new file mode 100644 index 0000000000000000000000000000000000000000..769659c0dd27a13ff7cf7ed6a0a8690bc2b225bc GIT binary patch literal 2755 zcmc&#_g9k%7L7V;C}JQW5)t??h#{pp@}-+A|(ch7z2-F0%XJ|K<|hd>|) zY;7!15Xc@C2xRw_-Ftp8Q-?7VKS0vyqKl=pwDgRNiby1q!m7aERD%NtyjXx3jV20Ytoaoa>3`{bXfo``v72dt2;oN77Ecsd;Chc8CS`%J=!C)_7&0go?v| zdIXM#y4VP|7X?0gGW76ld`6I5xM&B|Uw;X84+7@4Yw-^S!35CHY&AG4EX$<7SNSxC zdvN$`a#ISsA4fNTrSOI+Mq{t`rnk5{dTjOddLDd_gPxCpPMux*af_mRsA%c3JS9E zuZM99mA4QGic*VMmUwOZ=rws?=Cbq9AYDKF-&sUgl`)y5BM}K%t>?;XN90SroL2Rt zYihTn8LbttndFJ}o~2MY$*461^vc*$kgS{w?Uqigag1$4dY?>C$C!^GG=z4h!> zc1`|7NR`&qc*<+z#7~>>oG&enzC15Q*~nRUl44sT6l&fX-Q@h_n+)2FckwyFVsV*T ze+wSG2GWi@k^Z@+m$$zc+FYbxx;Dy9>%(|=`}|DG&#*)!Cb_}t6oKT}_Hcc$+bw7p z7!!)_aqs+=5b$}|pV0+jL!WGZ77K{@_(0H={VjpBFDGw@yq1We9ni5`9k9R!xtat4 zmLWHX(3n85d%XfClTg#F7h|yDW9yuwYd~*TVtq>}D|UDM^U>wlsH3GDY4;nXnkBUY zS0utsTCN(UGgk_Z#k3~Ye0R!Y1+QaW;O~3-nH$5oCLCO|eD<$0s0KG_#{P0ez`u*X zaRQhyY+O+8vcr{N*p(rUVn3&N4nwNs)e1VjF z!E|a1#AzyEFVYInOthP_xPu{FO=5Fu@8vCUWnji5mc+iQ%+Gy(VIKhJt2qX&k8~7t z79&Hhv%}c0cvrkye0GtkvjbuLmxsYwzXjGl9QQIJt-y#dm- zwXOki*Q)T<1|?LnP}Ma+a3I-9tJr5=+I^XEp{r^6hV_HBbXoJ;F#g%jsIi7o&{RYZwxK z2j=Es5ZtEmB6Kmf@NNAM#XqvAGiEIR!GE4jAAT44F+zi!-u~L`0`b;8*Wl+#b*tut z^tf9|W3z3WjH3&%YHvxZdKxw&YvsG55TQxaI?P7x-;VD&^uD+xFnm1*>>fR9jx#$! zI|x=Yt;9Vk^#)ep<0AdManzRnc;r8Bi^Z=8M|sK1M+%K&;~o#rC!cI>xG`!Oir1e#l(!!2e7=xcpIrivc;EXk?_xW#c(6k)_E9py zQb(Dtu=(mC{(61x^C^qjqd<$dtZJ0XRbX~PtuW83@|A%bPw%EBz&M-p2p++9$f6Nj z7-F>Na zQ(rf^NbXadz5d+tt?dOjkJ~qU&ZX1kMm-#qImLdisP*e$^;e;Tq^VB>yUHZ<lde z)6U&W0bZ$(;%ELqp}$tRLY`D^NxWHD*J{vyL~zL1KREebTb~F zFyut!A1CId#Kzilw#HO!&yiQ{&qAkb0HQfs7il!zIP?{*(?%JcLQWCKP)&M3xlNU2 zmgI*jJsp1-st~+Mda`))p^U1j8z;W732%;@3-z$+pZ(HkuajtNgD6dC&>`F6lp``P=J$@0dNB$fnv7o{?CtgmvhoKXB+ko~}0K*)eulnO%T$!zr&ToqMhAXl}SY)MJbQZ?8YYM zSnimrO;VTPOA{R^tYCS0WNa)s+4DADStL;3(FQwnIMB_xp0d79>W|N~5DSD%*6_@z zw(`bdK&C>eR=^i%xHdWCH`mi}M!Rb462SF$S%%99{IGrA?6lt@z!oM*7fF^@X0cUu zszSoEJlo3}?jxiDiEGC$S;0kr>_#LAWhrR0|H%E%ptehbgAa_4q+a^&ukw?$wREtk I27Oci0#i{cZU6uP literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-refresh.png b/doc/tutorial/figures/sbs-refresh.png new file mode 100644 index 0000000000000000000000000000000000000000..f63bf93a2f84f45baa106645b41176fcb003784b GIT binary patch literal 2980 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 literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-ssh.png b/doc/tutorial/figures/sbs-ssh.png new file mode 100644 index 0000000000000000000000000000000000000000..cf7ffa6e69a6fc003854892d72b47af1f0a8ed98 GIT binary patch literal 2328 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 literal 0 HcmV?d00001 diff --git a/doc/tutorial/figures/sbs-storage.png b/doc/tutorial/figures/sbs-storage.png new file mode 100644 index 0000000000000000000000000000000000000000..44956b1b885c2cda5073bb398ed9bf03971338ab GIT binary patch literal 3982 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 literal 0 HcmV?d00001 diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index faefeab3..08cd5074 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -11,8 +11,8 @@ capable of. ----- -Introduction to autoinstall -=========================== +For Ubuntu Server +================= This tutorial introduces the core concepts of autoinstall and is recommended as the first step. @@ -20,4 +20,6 @@ the first step. .. toctree:: :maxdepth: 1 - intro-to-autoinstall.rst + basic-server-installation + screen-by-screen + diff --git a/doc/tutorial/screen-by-screen.rst b/doc/tutorial/screen-by-screen.rst new file mode 100644 index 00000000..4afdf9e1 --- /dev/null +++ b/doc/tutorial/screen-by-screen.rst @@ -0,0 +1,174 @@ +Screen-by-screen installer +************************** + +The installer is designed to be easy to use without documentation. However, +this guide provides more information on each of the screens of the installer to +help walk you through an installation. + +Language selection +================== + +.. image:: figures/sbs-language.png + :alt: + +This screen selects the language for the installer and the default language +for the installed system. + +More languages can be displayed if you +`connect via SSH `_. + +Refresh +======= + +.. image:: figures/sbs-refresh.png + :alt: + +This screen is shown if there is an update available for the installer. This +allows you to get any improvements and bug fixes made since release. + +If you choose to update, the new version will be downloaded and the installer +will restart at the same point of the installation. + +Keyboard +======== + +.. image:: figures/sbs-keyboard.png + :alt: + +Choose the layout and variant of keyboard attached to the system, if any. When +running in a virtual terminal, it is possible to guess the layout and variant +by answering questions about the keyboard. + +Zdev (s390x only) +================= + +.. code-block:: + + ==================================================================== + Zdev setup + ==================================================================== + ID ONLINE NAMES ^ + │ + generic-ccw │ + 0.0.0009 > │ + 0.0.000c > │ + 0.0.000d > │ + 0.0.000e > │ + │ + dasd-eckd │ + 0.0.0190 > │ + 0.0.0191 > │ + 0.0.019d > │ + 0.0.019e >┌────────────┐ + 0.0.0200 >│< (close) │ + 0.0.0300 >│ Enable │ + 0.0.0400 >│ Disable │ + 0.0.0592 >└────────────┘ v + + [ Continue ] + [ Back ] + + +This screen is only shown on s390x and allows z-specific configuration of +devices. + +The list of devices can be long. :kbd:`Home` / :kbd:`End` / :kbd:`PageUp` +/ :kbd:`PageDown` can be used to navigate through the list more quickly. + +Network +======= + +.. image:: figures/sbs-network.png + :alt: + +This screen allows the configuration of the network. Ubuntu Server uses NetPlan +to configure networking and the UI of the installer can configure a subset of +NetPlan's capabilities. In particular it can configure DHCP or static +addressing, VLANs and bonds. + +If networking is present (defined as "at least one interface has a default +route") then the installer will install updates from the archive at the end of +installation. + +Proxy +===== + +.. image:: figures/sbs-proxy.png + :alt: + +The proxy configured on this screen is used for accessing the package +repository and the snap store both in the installer environment and in the +installed system. + +Mirror +====== + +.. image:: figures/sbs-mirror.png + :alt: + +The installer will attempt to use ``geoip`` to look up an appropriate default +package mirror for your location. If you want or need to use a different +mirror, enter its URL here. + +Storage +======= + +.. image:: figures/sbs-storage.png + :alt: + +Storage configuration is a complicated topic and :ref:`has its own page for documentation `. + +.. image:: figures/sbs-confirm-storage.png + :alt: + +Once the storage configuration is confirmed, the install begins in the +background. + +Identity +======== + +.. image:: figures/sbs-identity.png + :alt: + +The default user will be an administrator, able to use ``sudo`` (this is why a +password is needed, even if SSH public key access is enabled on the next +screen). + +SSH +=== + +.. image:: figures/sbs-ssh.png + :alt: + +A default Ubuntu install has no open ports. It is very common to administer +servers via SSH so the installer allows it to be installed with the click of a +button. + +You can import keys for the default user from GitHub or Launchpad. + +If you import a key, then password authentication is disabled by default but it +can be re-enabled again at a later time if you wish. + +Snaps +===== + +.. image:: figures/sbs-snaps.png + :alt: + +If a network connection is enabled, a selection of snaps that are useful in a +server environment are presented and can be selected for installation. + +Installation logs +================= + +.. image:: figures/sbs-logs.png + :alt: + +The final screen of the installer shows the progress of the installer and +allows viewing of the full log file. Once the install has completed and +security updates installed, the installer waits for confirmation before +restarting. + +.. image:: figures/sbs-complete.png + :alt: +