├── .gitignore ├── LICENSE ├── Makefile.am ├── README.rst ├── autogen.sh ├── configure.ac ├── os-core.7.rst ├── os-format.7.rst └── stateless.7.rst /.gitignore: -------------------------------------------------------------------------------- 1 | *.7 2 | Makefile 3 | Makefile.in 4 | aclocal.m4 5 | autom4te.cache/ 6 | clr-man-pages-*.tar.xz 7 | config.log 8 | config.status 9 | configure 10 | install-sh 11 | missing 12 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | Attribution-ShareAlike 3.0 Unported 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR 10 | DAMAGES RESULTING FROM ITS USE. 11 | 12 | License 13 | 14 | THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE 15 | COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY 16 | COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS 17 | AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. 18 | 19 | BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE 20 | TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY 21 | BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS 22 | CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND 23 | CONDITIONS. 24 | 25 | 1. Definitions 26 | 27 | a. "Adaptation" means a work based upon the Work, or upon the Work and 28 | other pre-existing works, such as a translation, adaptation, 29 | derivative work, arrangement of music or other alterations of a 30 | literary or artistic work, or phonogram or performance and includes 31 | cinematographic adaptations or any other form in which the Work may be 32 | recast, transformed, or adapted including in any form recognizably 33 | derived from the original, except that a work that constitutes a 34 | Collection will not be considered an Adaptation for the purpose of 35 | this License. For the avoidance of doubt, where the Work is a musical 36 | work, performance or phonogram, the synchronization of the Work in 37 | timed-relation with a moving image ("synching") will be considered an 38 | Adaptation for the purpose of this License. 39 | b. "Collection" means a collection of literary or artistic works, such as 40 | encyclopedias and anthologies, or performances, phonograms or 41 | broadcasts, or other works or subject matter other than works listed 42 | in Section 1(f) below, which, by reason of the selection and 43 | arrangement of their contents, constitute intellectual creations, in 44 | which the Work is included in its entirety in unmodified form along 45 | with one or more other contributions, each constituting separate and 46 | independent works in themselves, which together are assembled into a 47 | collective whole. A work that constitutes a Collection will not be 48 | considered an Adaptation (as defined below) for the purposes of this 49 | License. 50 | c. "Creative Commons Compatible License" means a license that is listed 51 | at https://creativecommons.org/compatiblelicenses that has been 52 | approved by Creative Commons as being essentially equivalent to this 53 | License, including, at a minimum, because that license: (i) contains 54 | terms that have the same purpose, meaning and effect as the License 55 | Elements of this License; and, (ii) explicitly permits the relicensing 56 | of adaptations of works made available under that license under this 57 | License or a Creative Commons jurisdiction license with the same 58 | License Elements as this License. 59 | d. "Distribute" means to make available to the public the original and 60 | copies of the Work or Adaptation, as appropriate, through sale or 61 | other transfer of ownership. 62 | e. "License Elements" means the following high-level license attributes 63 | as selected by Licensor and indicated in the title of this License: 64 | Attribution, ShareAlike. 65 | f. "Licensor" means the individual, individuals, entity or entities that 66 | offer(s) the Work under the terms of this License. 67 | g. "Original Author" means, in the case of a literary or artistic work, 68 | the individual, individuals, entity or entities who created the Work 69 | or if no individual or entity can be identified, the publisher; and in 70 | addition (i) in the case of a performance the actors, singers, 71 | musicians, dancers, and other persons who act, sing, deliver, declaim, 72 | play in, interpret or otherwise perform literary or artistic works or 73 | expressions of folklore; (ii) in the case of a phonogram the producer 74 | being the person or legal entity who first fixes the sounds of a 75 | performance or other sounds; and, (iii) in the case of broadcasts, the 76 | organization that transmits the broadcast. 77 | h. "Work" means the literary and/or artistic work offered under the terms 78 | of this License including without limitation any production in the 79 | literary, scientific and artistic domain, whatever may be the mode or 80 | form of its expression including digital form, such as a book, 81 | pamphlet and other writing; a lecture, address, sermon or other work 82 | of the same nature; a dramatic or dramatico-musical work; a 83 | choreographic work or entertainment in dumb show; a musical 84 | composition with or without words; a cinematographic work to which are 85 | assimilated works expressed by a process analogous to cinematography; 86 | a work of drawing, painting, architecture, sculpture, engraving or 87 | lithography; a photographic work to which are assimilated works 88 | expressed by a process analogous to photography; a work of applied 89 | art; an illustration, map, plan, sketch or three-dimensional work 90 | relative to geography, topography, architecture or science; a 91 | performance; a broadcast; a phonogram; a compilation of data to the 92 | extent it is protected as a copyrightable work; or a work performed by 93 | a variety or circus performer to the extent it is not otherwise 94 | considered a literary or artistic work. 95 | i. "You" means an individual or entity exercising rights under this 96 | License who has not previously violated the terms of this License with 97 | respect to the Work, or who has received express permission from the 98 | Licensor to exercise rights under this License despite a previous 99 | violation. 100 | j. "Publicly Perform" means to perform public recitations of the Work and 101 | to communicate to the public those public recitations, by any means or 102 | process, including by wire or wireless means or public digital 103 | performances; to make available to the public Works in such a way that 104 | members of the public may access these Works from a place and at a 105 | place individually chosen by them; to perform the Work to the public 106 | by any means or process and the communication to the public of the 107 | performances of the Work, including by public digital performance; to 108 | broadcast and rebroadcast the Work by any means including signs, 109 | sounds or images. 110 | k. "Reproduce" means to make copies of the Work by any means including 111 | without limitation by sound or visual recordings and the right of 112 | fixation and reproducing fixations of the Work, including storage of a 113 | protected performance or phonogram in digital form or other electronic 114 | medium. 115 | 116 | 2. Fair Dealing Rights. Nothing in this License is intended to reduce, 117 | limit, or restrict any uses free from copyright or rights arising from 118 | limitations or exceptions that are provided for in connection with the 119 | copyright protection under copyright law or other applicable laws. 120 | 121 | 3. License Grant. Subject to the terms and conditions of this License, 122 | Licensor hereby grants You a worldwide, royalty-free, non-exclusive, 123 | perpetual (for the duration of the applicable copyright) license to 124 | exercise the rights in the Work as stated below: 125 | 126 | a. to Reproduce the Work, to incorporate the Work into one or more 127 | Collections, and to Reproduce the Work as incorporated in the 128 | Collections; 129 | b. to create and Reproduce Adaptations provided that any such Adaptation, 130 | including any translation in any medium, takes reasonable steps to 131 | clearly label, demarcate or otherwise identify that changes were made 132 | to the original Work. For example, a translation could be marked "The 133 | original work was translated from English to Spanish," or a 134 | modification could indicate "The original work has been modified."; 135 | c. to Distribute and Publicly Perform the Work including as incorporated 136 | in Collections; and, 137 | d. to Distribute and Publicly Perform Adaptations. 138 | e. For the avoidance of doubt: 139 | 140 | i. Non-waivable Compulsory License Schemes. In those jurisdictions in 141 | which the right to collect royalties through any statutory or 142 | compulsory licensing scheme cannot be waived, the Licensor 143 | reserves the exclusive right to collect such royalties for any 144 | exercise by You of the rights granted under this License; 145 | ii. Waivable Compulsory License Schemes. In those jurisdictions in 146 | which the right to collect royalties through any statutory or 147 | compulsory licensing scheme can be waived, the Licensor waives the 148 | exclusive right to collect such royalties for any exercise by You 149 | of the rights granted under this License; and, 150 | iii. Voluntary License Schemes. The Licensor waives the right to 151 | collect royalties, whether individually or, in the event that the 152 | Licensor is a member of a collecting society that administers 153 | voluntary licensing schemes, via that society, from any exercise 154 | by You of the rights granted under this License. 155 | 156 | The above rights may be exercised in all media and formats whether now 157 | known or hereafter devised. The above rights include the right to make 158 | such modifications as are technically necessary to exercise the rights in 159 | other media and formats. Subject to Section 8(f), all rights not expressly 160 | granted by Licensor are hereby reserved. 161 | 162 | 4. Restrictions. The license granted in Section 3 above is expressly made 163 | subject to and limited by the following restrictions: 164 | 165 | a. You may Distribute or Publicly Perform the Work only under the terms 166 | of this License. You must include a copy of, or the Uniform Resource 167 | Identifier (URI) for, this License with every copy of the Work You 168 | Distribute or Publicly Perform. You may not offer or impose any terms 169 | on the Work that restrict the terms of this License or the ability of 170 | the recipient of the Work to exercise the rights granted to that 171 | recipient under the terms of the License. You may not sublicense the 172 | Work. You must keep intact all notices that refer to this License and 173 | to the disclaimer of warranties with every copy of the Work You 174 | Distribute or Publicly Perform. When You Distribute or Publicly 175 | Perform the Work, You may not impose any effective technological 176 | measures on the Work that restrict the ability of a recipient of the 177 | Work from You to exercise the rights granted to that recipient under 178 | the terms of the License. This Section 4(a) applies to the Work as 179 | incorporated in a Collection, but this does not require the Collection 180 | apart from the Work itself to be made subject to the terms of this 181 | License. If You create a Collection, upon notice from any Licensor You 182 | must, to the extent practicable, remove from the Collection any credit 183 | as required by Section 4(c), as requested. If You create an 184 | Adaptation, upon notice from any Licensor You must, to the extent 185 | practicable, remove from the Adaptation any credit as required by 186 | Section 4(c), as requested. 187 | b. You may Distribute or Publicly Perform an Adaptation only under the 188 | terms of: (i) this License; (ii) a later version of this License with 189 | the same License Elements as this License; (iii) a Creative Commons 190 | jurisdiction license (either this or a later license version) that 191 | contains the same License Elements as this License (e.g., 192 | Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible 193 | License. If you license the Adaptation under one of the licenses 194 | mentioned in (iv), you must comply with the terms of that license. If 195 | you license the Adaptation under the terms of any of the licenses 196 | mentioned in (i), (ii) or (iii) (the "Applicable License"), you must 197 | comply with the terms of the Applicable License generally and the 198 | following provisions: (I) You must include a copy of, or the URI for, 199 | the Applicable License with every copy of each Adaptation You 200 | Distribute or Publicly Perform; (II) You may not offer or impose any 201 | terms on the Adaptation that restrict the terms of the Applicable 202 | License or the ability of the recipient of the Adaptation to exercise 203 | the rights granted to that recipient under the terms of the Applicable 204 | License; (III) You must keep intact all notices that refer to the 205 | Applicable License and to the disclaimer of warranties with every copy 206 | of the Work as included in the Adaptation You Distribute or Publicly 207 | Perform; (IV) when You Distribute or Publicly Perform the Adaptation, 208 | You may not impose any effective technological measures on the 209 | Adaptation that restrict the ability of a recipient of the Adaptation 210 | from You to exercise the rights granted to that recipient under the 211 | terms of the Applicable License. This Section 4(b) applies to the 212 | Adaptation as incorporated in a Collection, but this does not require 213 | the Collection apart from the Adaptation itself to be made subject to 214 | the terms of the Applicable License. 215 | c. If You Distribute, or Publicly Perform the Work or any Adaptations or 216 | Collections, You must, unless a request has been made pursuant to 217 | Section 4(a), keep intact all copyright notices for the Work and 218 | provide, reasonable to the medium or means You are utilizing: (i) the 219 | name of the Original Author (or pseudonym, if applicable) if supplied, 220 | and/or if the Original Author and/or Licensor designate another party 221 | or parties (e.g., a sponsor institute, publishing entity, journal) for 222 | attribution ("Attribution Parties") in Licensor's copyright notice, 223 | terms of service or by other reasonable means, the name of such party 224 | or parties; (ii) the title of the Work if supplied; (iii) to the 225 | extent reasonably practicable, the URI, if any, that Licensor 226 | specifies to be associated with the Work, unless such URI does not 227 | refer to the copyright notice or licensing information for the Work; 228 | and (iv) , consistent with Ssection 3(b), in the case of an 229 | Adaptation, a credit identifying the use of the Work in the Adaptation 230 | (e.g., "French translation of the Work by Original Author," or 231 | "Screenplay based on original Work by Original Author"). The credit 232 | required by this Section 4(c) may be implemented in any reasonable 233 | manner; provided, however, that in the case of a Adaptation or 234 | Collection, at a minimum such credit will appear, if a credit for all 235 | contributing authors of the Adaptation or Collection appears, then as 236 | part of these credits and in a manner at least as prominent as the 237 | credits for the other contributing authors. For the avoidance of 238 | doubt, You may only use the credit required by this Section for the 239 | purpose of attribution in the manner set out above and, by exercising 240 | Your rights under this License, You may not implicitly or explicitly 241 | assert or imply any connection with, sponsorship or endorsement by the 242 | Original Author, Licensor and/or Attribution Parties, as appropriate, 243 | of You or Your use of the Work, without the separate, express prior 244 | written permission of the Original Author, Licensor and/or Attribution 245 | Parties. 246 | d. Except as otherwise agreed in writing by the Licensor or as may be 247 | otherwise permitted by applicable law, if You Reproduce, Distribute or 248 | Publicly Perform the Work either by itself or as part of any 249 | Adaptations or Collections, You must not distort, mutilate, modify or 250 | take other derogatory action in relation to the Work which would be 251 | prejudicial to the Original Author's honor or reputation. Licensor 252 | agrees that in those jurisdictions (e.g. Japan), in which any exercise 253 | of the right granted in Section 3(b) of this License (the right to 254 | make Adaptations) would be deemed to be a distortion, mutilation, 255 | modification or other derogatory action prejudicial to the Original 256 | Author's honor and reputation, the Licensor will waive or not assert, 257 | as appropriate, this Section, to the fullest extent permitted by the 258 | applicable national law, to enable You to reasonably exercise Your 259 | right under Section 3(b) of this License (right to make Adaptations) 260 | but not otherwise. 261 | 262 | 5. Representations, Warranties and Disclaimer 263 | 264 | UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR 265 | OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY 266 | KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, 267 | INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, 268 | FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF 269 | LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, 270 | WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION 271 | OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. 272 | 273 | 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE 274 | LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR 275 | ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES 276 | ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS 277 | BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 278 | 279 | 7. Termination 280 | 281 | a. This License and the rights granted hereunder will terminate 282 | automatically upon any breach by You of the terms of this License. 283 | Individuals or entities who have received Adaptations or Collections 284 | from You under this License, however, will not have their licenses 285 | terminated provided such individuals or entities remain in full 286 | compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will 287 | survive any termination of this License. 288 | b. Subject to the above terms and conditions, the license granted here is 289 | perpetual (for the duration of the applicable copyright in the Work). 290 | Notwithstanding the above, Licensor reserves the right to release the 291 | Work under different license terms or to stop distributing the Work at 292 | any time; provided, however that any such election will not serve to 293 | withdraw this License (or any other license that has been, or is 294 | required to be, granted under the terms of this License), and this 295 | License will continue in full force and effect unless terminated as 296 | stated above. 297 | 298 | 8. Miscellaneous 299 | 300 | a. Each time You Distribute or Publicly Perform the Work or a Collection, 301 | the Licensor offers to the recipient a license to the Work on the same 302 | terms and conditions as the license granted to You under this License. 303 | b. Each time You Distribute or Publicly Perform an Adaptation, Licensor 304 | offers to the recipient a license to the original Work on the same 305 | terms and conditions as the license granted to You under this License. 306 | c. If any provision of this License is invalid or unenforceable under 307 | applicable law, it shall not affect the validity or enforceability of 308 | the remainder of the terms of this License, and without further action 309 | by the parties to this agreement, such provision shall be reformed to 310 | the minimum extent necessary to make such provision valid and 311 | enforceable. 312 | d. No term or provision of this License shall be deemed waived and no 313 | breach consented to unless such waiver or consent shall be in writing 314 | and signed by the party to be charged with such waiver or consent. 315 | e. This License constitutes the entire agreement between the parties with 316 | respect to the Work licensed here. There are no understandings, 317 | agreements or representations with respect to the Work not specified 318 | here. Licensor shall not be bound by any additional provisions that 319 | may appear in any communication from You. This License may not be 320 | modified without the mutual written agreement of the Licensor and You. 321 | f. The rights granted under, and the subject matter referenced, in this 322 | License were drafted utilizing the terminology of the Berne Convention 323 | for the Protection of Literary and Artistic Works (as amended on 324 | September 28, 1979), the Rome Convention of 1961, the WIPO Copyright 325 | Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 326 | and the Universal Copyright Convention (as revised on July 24, 1971). 327 | These rights and subject matter take effect in the relevant 328 | jurisdiction in which the License terms are sought to be enforced 329 | according to the corresponding provisions of the implementation of 330 | those treaty provisions in the applicable national law. If the 331 | standard suite of rights granted under applicable copyright law 332 | includes additional rights not granted under this License, such 333 | additional rights are deemed to be included in the License; this 334 | License is not intended to restrict the license of any rights under 335 | applicable law. 336 | 337 | 338 | Creative Commons Notice 339 | 340 | Creative Commons is not a party to this License, and makes no warranty 341 | whatsoever in connection with the Work. Creative Commons will not be 342 | liable to You or any party on any legal theory for any damages 343 | whatsoever, including without limitation any general, special, 344 | incidental or consequential damages arising in connection to this 345 | license. Notwithstanding the foregoing two (2) sentences, if Creative 346 | Commons has expressly identified itself as the Licensor hereunder, it 347 | shall have all rights and obligations of Licensor. 348 | 349 | Except for the limited purpose of indicating to the public that the 350 | Work is licensed under the CCPL, Creative Commons does not authorize 351 | the use by either party of the trademark "Creative Commons" or any 352 | related trademark or logo of Creative Commons without the prior 353 | written consent of Creative Commons. Any permitted use will be in 354 | compliance with Creative Commons' then-current trademark usage 355 | guidelines, as may be published on its website or otherwise made 356 | available upon request from time to time. For the avoidance of doubt, 357 | this trademark restriction does not form part of the License. 358 | 359 | Creative Commons may be contacted at https://creativecommons.org/. 360 | -------------------------------------------------------------------------------- /Makefile.am: -------------------------------------------------------------------------------- 1 | EXTRA_DIST = \ 2 | README.rst \ 3 | LICENSE \ 4 | os-format.7 \ 5 | os-format.7.rst \ 6 | os-core.7 \ 7 | os-core.7.rst \ 8 | stateless.7 \ 9 | stateless.7.rst 10 | 11 | dist_man_MANS = \ 12 | os-format.7 \ 13 | os-core.7 \ 14 | stateless.7 15 | 16 | clean-local: 17 | rm -f $(dist_man_MANS) 18 | 19 | man: $(dist_man_MANS) 20 | 21 | %: %.rst 22 | rst2man.py $< > $@ 23 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | 2 | clr-man-pages 3 | ============= 4 | 5 | Provides a few extra man pages that describes the particularities 6 | of Clear Linux OS for Intel Architecture, and some useful tips 7 | and tricks for the most frequently asked questions. 8 | 9 | -------------------------------------------------------------------------------- /autogen.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | autoreconf --force --install --symlink --warnings=all 6 | 7 | args="\ 8 | --prefix=/usr \ 9 | --enable-silent-rules" 10 | 11 | ./configure $args "$@" 12 | -------------------------------------------------------------------------------- /configure.ac: -------------------------------------------------------------------------------- 1 | # -*- Autoconf -*- 2 | # Process this file with autoconf to produce a configure script. 3 | 4 | AC_PREREQ([2.69]) 5 | AC_INIT([clr-man-pages], [12], [dev@lists.clearlinux.org]) 6 | AM_INIT_AUTOMAKE([foreign -Wall -W subdir-objects no-dist-gzip dist-xz]) 7 | AM_SILENT_RULES([yes]) 8 | 9 | AC_CONFIG_SRCDIR([stateless.7.rst]) 10 | 11 | # Checks for programs. 12 | # Checks for header files. 13 | # Checks for typedefs, structures, and compiler characteristics. 14 | # Checks for library functions. 15 | 16 | AC_CONFIG_FILES([Makefile]) 17 | AC_OUTPUT 18 | -------------------------------------------------------------------------------- /os-core.7.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | os-core 3 | ======= 4 | 5 | ---------------------------------------------------- 6 | Base files for Clear Linux OS for Intel Architecture 7 | ---------------------------------------------------- 8 | 9 | :Copyright: \(C\) 2017 Intel Corporation, CC-BY-SA-3.0 10 | :Manual section: 7 11 | 12 | 13 | SYNOPSIS 14 | ======== 15 | 16 | * ``init`` 17 | * ``root filesystem`` 18 | * ``shell`` 19 | 20 | 21 | DESCRIPTION 22 | =========== 23 | 24 | os-core provides a minimal base for the Clear Linux OS for Intel 25 | Architecture. It contains required utilities for running the init 26 | program systemd, letting users log in and run bash shell commands. The 27 | core also contains pieces of packages that are required to run any 28 | other package in the distribution. 29 | 30 | This is the only required bundle for Clear Linux OS and can not be 31 | removed as all other bundles depend upon it. 32 | 33 | 34 | SEE ALSO 35 | ======== 36 | 37 | ``_ 38 | -------------------------------------------------------------------------------- /os-format.7.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | OS Format 3 | ========= 4 | 5 | -------------------------------------- 6 | A summary of OS formats in Clear Linux 7 | -------------------------------------- 8 | 9 | :Copyright: \(C) 2018 Intel Corporation, CC-BY-SA-3.0 10 | :Manual section: 7 11 | 12 | 13 | SYNOPSIS 14 | ======== 15 | 16 | ``/usr/share/defaults/swupd/format`` 17 | 18 | DESCRIPTION 19 | =========== 20 | 21 | A format defines a range of OS versions that have compatible update metadata and 22 | content. An update client can update a system from the oldest version in the 23 | format to the latest version in the format without worrying about compatibility 24 | issues in the update content for the version it is updating to. 25 | 26 | A format bump occurs when the update metadata or content is changed in such a 27 | way that will cause client updates to break. In this case the format number must 28 | be incremented so clients will not attempt to update to the new versions in the 29 | new format without crossing the format boundary. Update clients update only to 30 | the latest build in their format. Once that update is complete the update client 31 | may then update forward again because the last version in the current format has 32 | identical content to the first version in the new format, including the new 33 | update client needed to understand the new format. 34 | 35 | Because the update system in Clear Linux (``swupd``) has auto-update turned on 36 | by default most users will never be aware of their system changing to a new 37 | format. Those users who have disabled auto-update may occasionally see ``swupd`` 38 | perform two updates in a row when they only invoked ``swupd update`` once. This 39 | is because ``swupd`` detects when it crossed a format boundary and immediately 40 | re-executes an update to carry it to the latest version in the new format. This 41 | re-execution will actually invoke the new version of ``swupd`` that was 42 | delivered in the first update. 43 | 44 | Format bumps are simply a way for Clear Linux to introduce breaking changes to 45 | the OS without breaking user's update stream or workflow. 46 | 47 | 48 | SEE ALSO 49 | ======== 50 | 51 | * ``mixer``\(1) 52 | * ``swupd``\(1) 53 | * https://clearlinux.org/documentation/ 54 | * https://github.com/clearlinux/swupd-client/ 55 | * https://github.com/clearlinux/mixer-tools/ 56 | -------------------------------------------------------------------------------- /stateless.7.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | stateless 3 | ========= 4 | 5 | --------------------------------------------------------------------------- 6 | A guide to stateless configuration in Clear Linux OS for Intel Architecture 7 | --------------------------------------------------------------------------- 8 | 9 | :Copyright: \(C) 2017 Intel Corporation, CC-BY-SA-3.0 10 | :Manual section: 7 11 | 12 | 13 | SYNOPSIS 14 | ======== 15 | 16 | ``/etc/`` 17 | 18 | ``/usr/share/defaults/`` 19 | 20 | ``/usr/share/defaults/etc/`` 21 | 22 | ``/var/`` 23 | 24 | ``/var/cache/`` 25 | 26 | ``/usr/local/`` 27 | 28 | ``/usr/src/`` 29 | 30 | ``/usr/lib/kernel/`` 31 | 32 | ``/usr/lib/modules/`` 33 | 34 | 35 | DESCRIPTION 36 | =========== 37 | 38 | The Clear Linux OS for Intel Architecture has a unique way of 39 | providing customization and configuration to system administrators and 40 | users. This man page aims to provide both an explanation of what this 41 | method is and how users of Clear Linux can use it and benefit from it. 42 | 43 | The goal of "stateless" is to provide a system OS that functions 44 | without user configuration. A system should not require editing of 45 | configuration files by the end user before it is functional, nor should 46 | it place lengthy and confusing configuration files automatically in 47 | user-maintained file system areas (``/etc/``) by default. And 48 | additionally, any configuration placed in user-maintained configuration 49 | should be removable without breaking functionality. 50 | 51 | This is achieved by several methods, each of which implements a part 52 | of the stateless goal. 53 | 54 | 55 | * Removal of configuration files 56 | 57 | The first step taken to achieve stateless configuration is to embed 58 | proper default configuration values in the software. Any missing 59 | critical configuration value should have a built-in default value. 60 | 61 | * Providing of default configuration files outside of ``/etc/`` 62 | 63 | Software is adjusted to use a distribution provided default 64 | configuration file in ``/usr/share/defaults``. If no configuration 65 | file exists in ``/etc/`` for the software, the software must use the 66 | distribution default configuration file. 67 | 68 | * Allowing the end user to provide configuration in ``/etc/`` 69 | 70 | If the user provides a properly formatted configuration file in 71 | the ``/etc/`` filesystem area (or, wherever it is relevant for the 72 | software), the software is instructed to use this configuration 73 | file instead of any other. 74 | 75 | 76 | Consequences for the system administrator (user) 77 | ------------------------------------------------ 78 | 79 | The user should create configuration files as needed and avoid 80 | modifying distribution provided defaults. The filesystem folders and 81 | all content under ``/etc/`` and ``/var/`` may be modified as needed, but 82 | the content under ``/usr/``, ``/lib/``, ``/lib64/``, ``/bin/``, ``/sbin/`` should 83 | never be modified, and will be overwritten by ``swupd``\(1) as needed. 84 | 85 | Some default configuration structure and data is automatically created 86 | under ``/etc/`` and ``/var/``. The user may remove these file system 87 | structures entirely - a reboot of the OS should properly restore the 88 | system to its factory default. This may also provide the user with 89 | a way to repair a defective system configuration. 90 | 91 | The user should, if user configuration of a service is needed, 92 | attempt to place the configuration file in the ``/etc/`` structure as 93 | the service requests. Often, template files for the configuration 94 | format can be found under the ``/usr/share/defaults/`` file structure, 95 | and these files can be copied to the ``/etc/`` file structure. 96 | 97 | To modify system service configuration (``systemd``\(1) service units), 98 | the user should not touch or modify unit files under the ``/usr/`` 99 | file structure directly, as changes in those files will be lost after 100 | a system software update with ``swupd``\(1). 101 | 102 | A list of package specific hints and best practices is listed below. In 103 | many cases, the man pages for the respective packages also provides 104 | detailed information as to how to configure the software. Please 105 | consult the relevant manual pages for the software to find information 106 | on the specific syntax and options for each software. 107 | 108 | 109 | Where can I install system-wide files then? 110 | ------------------------------------------- 111 | 112 | ``swupd``\(1) has a list of exempted locations where the system 113 | administrator can place files that will not get overwritten or removed 114 | at all. The default whitelisted directories are: 115 | 116 | ``/usr/lib/modules`` 117 | ``/usr/lib/kernel`` 118 | ``/usr/local`` 119 | ``/usr/src`` 120 | 121 | Using these locations for your own software is highly recommended. Not 122 | only do these locations provide a standard FHS compliant way of adding 123 | local software, they are sufficiently separated from OS software that 124 | maintaining them will be much more simple. 125 | 126 | 127 | ldconfig 128 | -------- 129 | 130 | ``ldconfig``\(8) 131 | 132 | The default paths that the linker searches includes only ``/usr/lib64`` 133 | and paths below that. This explicitly omits ``/usr/local/``. If you 134 | compile libraries manually and install them in other paths, you may 135 | need to configure the ``ld.so``\(8) linker to find these before you run 136 | ``ldconfig``. For example: 137 | 138 | ``echo "/usr/local/lib" | sudo tee -a /etc/ld.so.conf`` 139 | 140 | ``sudo ldconfig`` 141 | 142 | 143 | systemd 144 | ------- 145 | 146 | ``systemd``\(1) 147 | 148 | Unit files can be created under ``/etc/systemd/system`` as needed and 149 | function normally. To override unit file options, the simplest method 150 | is to have ``systemctl``\(1) copy it for you by invoking it as: 151 | 152 | ``systemctl edit --full foo.service`` 153 | 154 | This creates an exact copy of the default unit file and invokes the 155 | editor for the user, allowing the user to override any part of the unit. 156 | 157 | Unit files can be started as normal with ``systemctl start ``. 158 | 159 | To enable services to start at boot time, use ``systemctl enable ``. 160 | 161 | 162 | sshd 163 | ---- 164 | 165 | ``sshd``\(8) 166 | ``sshd_config``\(5) 167 | 168 | The SSH daemon has all of its configuration built in and no template 169 | configuration file is present on the file system. The man page for 170 | ``sshd_config``\(5) explains the format, and it suffices to put only a 171 | single option in the file 172 | 173 | ``/etc/ssh/sshd_config`` 174 | 175 | For example, to enable X11 forwarding through sshd all one has to do is 176 | add one line containing ``X11Forwarding yes``. Other often used options 177 | include ``PermitRootLogin yes`` to allow root ssh login access, and the 178 | following 3 lines to disable password authentication entirely: 179 | 180 | ``ChallengeResponseAuthentication no`` 181 | 182 | ``PasswordAuthentication no`` 183 | 184 | ``UsePAM no`` 185 | 186 | To modify the listening port of sshd, one needs to determine whether 187 | ``sshd.socket`` or ``sshd.service`` is enabled first, since the methods 188 | for changing the port number depend on whether ``sshd``\(8) is controlling 189 | the port number, or whether ``systemd``\(1) is: 190 | 191 | ``systemctl is-enabled sshd.socket`` 192 | 193 | If enabled, the ``sshd.socket`` unit should be edited to modify the port: 194 | 195 | ``systemctl edit --full sshd.socket`` 196 | 197 | And, the user should modify the port number at ``ListenStream=`` to the 198 | desired new port number. 199 | 200 | If ``sshd.service`` is enabled, the user should create, and edit a new 201 | ``/etc/ssh/sshd_config`` file: 202 | 203 | ``mkdir -p /etc/ssh/`` 204 | ``vi /etc/ssh/sshd_config`` 205 | 206 | And add a line in that file that reads: 207 | 208 | ``Port 10022`` 209 | 210 | to, for instance, change the port number sshd.service will listen on 211 | to port 10022. 212 | 213 | Root login over SSH is disabled by default and should remain disabled 214 | for most systemd. However, in some cases this is acceptable and it can 215 | be easily enabled by adding the following line to ``/etc/ssh/sshd_config`` 216 | that reads: 217 | 218 | ``PermitRootLogin yes`` 219 | 220 | 221 | nginx 222 | ----- 223 | 224 | Nginx ships by default in a non-functional configuration. However, 225 | an example configuration file is present that can be used to enable 226 | a simple server. To use this template configuration, create: 227 | 228 | ``mkdir -p /etc/nginx/conf.d`` 229 | 230 | And then copy configuration templates over to this folder: 231 | 232 | ``cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf`` 233 | ``cp /usr/share/nginx/conf/server.conf.example /etc/nginx/conf.d/server.conf`` 234 | 235 | Edit the file to assure options such as SSL and PHP are enabled in 236 | the preferred method. In the default configuration, PHP is enabled 237 | to run listening to ``/run/php-fpm.sock``. The template file has PHP 238 | by default disabled, but the listed example lines can be uncommented 239 | to make the nginx service process php documents. 240 | 241 | 242 | php-fpm 243 | ------- 244 | 245 | ``php-fpm``\(8) 246 | 247 | Php's default configuration file doesn't allow us to provide an 248 | alternative as it is programmed to only read the builtin file. If you 249 | wish to have php-fpm use a different configuration, you must pass it a 250 | startup option to tell it where it is. This can be done by ``systemctl 251 | edit --full php-fpm.service``. That command copies the default php-fpm 252 | service unit to ``/etc/systemd/system/`` and allows the user to override 253 | any option. It spawns an editor with the copy. 254 | 255 | Then, the user should change the line: 256 | 257 | ``ExecStart=/usr/sbin/php-fpm --nodaemonize`` 258 | 259 | to: 260 | 261 | ``ExecStart=/usr/sbin/php-fpm --nodaemonize --fpm-config /etc/php-fpm.conf`` 262 | 263 | The template php-fpm.conf can be found at ``/usr/share/defaults/php/php-fpm.conf``. 264 | One should copy this to a place in ``/etc/``: 265 | 266 | ``cp /usr/share/defaults/php/php-fpm.conf /etc/php-fpm.conf`` 267 | 268 | Then, the user should edit ``/etc/php-fpm.conf`` and assure that 269 | configuration options are all properly set as needed. 270 | 271 | Care must be taken using the default ``pool`` configuration. If needed, 272 | the user should also create ``/etc/php-fpm.d/`` and include pool 273 | configuration files from either ``/usr/share/defaults/php/php-fpm.d/`` or 274 | copy them and modify them as needed as well, as well as adjust the 275 | ``include`` configuration option in ``php-fpm.conf`` to point to a new 276 | location for pool configuration files. 277 | 278 | Network interface management 279 | ---------------------------- 280 | 281 | Clear Linux has switched the network interface management model to be fully 282 | managed by NetworkManager when installed on real hardware. Previously, Ethernet 283 | interfaces were managed by systemd-networkd whereas Wi-Fi and others were 284 | managed by NetworkManager. Clear Linux cloud images continue to use 285 | systemd-networkd. 286 | 287 | When updating from previous versions of Clear Linux, the installation will be 288 | reconfigured to continue with systemd-networkd managing the Ethernet interfaces. 289 | Since the connectivity could be lost during the procedure, physical access to the 290 | system is required. To switch to NetworkManager for all the interfaces, the 291 | user should disable and stop systemd-networkd: 292 | 293 | ``sudo systemctl disable systemd-networkd`` 294 | ``sudo systemctl stop systemd-networkd`` 295 | 296 | Then, remove the file ``/etc/NetworkManager/conf.d/systemd-networkd-unmanaged.conf`` 297 | 298 | Finally, restart NetworkManager 299 | 300 | ``sudo systemctl restart NetworkManager`` 301 | 302 | SEE ALSO 303 | ======== 304 | 305 | * ``swupd``\(1) 306 | * ``systemd``\(1) 307 | * https://clearlinux.org/documentation/ 308 | * https://clearlinux.org/features/stateless 309 | * https://github.com/clearlinux/swupd-client/ 310 | --------------------------------------------------------------------------------