commit 9698188caa6ddb376a831318eaa7e4c9cf94ff2a Author: Tracker-Friendly Date: Tue Oct 24 00:47:09 2023 +0100 Migrated, also removed codeberg from everywhere diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 0000000..1dc2d04 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -0,0 +1,12 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +*Before opening an issue, please be sure to check [what content is suitable for the Handbook](https://docs.voidlinux.org/about/about-this-handbook.html).* + +We prioritise issues about information specific to Void, and try to avoid duplicating information already available elsewhere (e.g. on the Arch wiki). diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 0000000..d330222 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,12 @@ +--- +name: Feature request +about: Suggest an idea for the Handbook +title: '' +labels: '' +assignees: '' + +--- + +*Before opening a request, please be sure to check [what content is suitable for the Handbook](https://docs.voidlinux.org/about/about-this-handbook.html).* + +We prioritise requests for information specific to Void, and try to avoid duplicating information already available elsewhere (e.g. on the Arch wiki). diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..c94f659 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,3 @@ +Before submitting a pull request, please read [CONTRIBUTING](https://github.com/void-linux/void-docs/blob/master/CONTRIBUTING.md); pull requests that do not meet the criteria described there will not be merged. Note that this repository's CONTRIBUTING contains information specific to this repository, and is not the same as CONTRIBUTING for the void-packages repository. + +We prioritise pull requests involving information specific to Void over those involving information applicable to Linux in general. diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..262b135 --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,42 @@ +name: Check PR +on: + pull_request: + paths: + - 'src/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + contents: + name: Check formatting and links + runs-on: ubuntu-latest + container: + image: ghcr.io/void-linux/void-linux:latest-full-x86_64-musl + steps: + - name: Prepare container + run: | + xbps-install -Syu || xbps-install -Syu xbps + xbps-install -yu + xbps-install -y mdbook-linkcheck vmdfmt git findutils bash + - name: Checkout + id: checkout + uses: classabbyamp/treeless-checkout-action@v1 + - name: Check summary + if: steps.checkout.conclusion == 'success' + run: res/ci/check-summary.sh + - name: Check formatting + if: success() || failure() + run: res/ci/format.sh + - name: Check links + if: success() || failure() + run: res/ci/linkcheck.sh + commits: + name: Check commits + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: classabbyamp/treeless-checkout-action@v1 + - name: Check commit messages + run: res/ci/commit-lint.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2f2d1ba --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +book/ +mandoc/ +res/void-docs +res/void-docs.1 +res/handbook-cover.png diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c4ab43b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,358 @@ +# Contributing + +To contribute to the EvolutionOS documentation, please read the following. Pull +requests that do not meet the criteria described below will not be merged. +Before submitting a PR: + +- try to address as many of the criteria as possible; and +- run the `check.sh` script provided in the repository root, addressing any + issues it reports. + +This will improve the chances of your contribution being accepted quickly. + +## Contents + +- [Suitable Content](#suitable-content) +- [Style Guide](#style-guide) +- [Submitting Changes](#submitting-changes) + +## Suitable content + +The Handbook is not intended to be a general guide to using a Linux system, as +[noted in the "About" +section](https://evolution-linux.github.io/wiki/about/about-this-handbook.html): + +> This handbook is not an extensive guide on how to use and configure common +> Linux software. The purpose of this document is to explain how to install, +> configure, and maintain EvolutionOS systems, and to highlight the differences +> between common Linux distributions and EvolutionOS ... +> +> Those looking for tips and tricks on how to configure a Linux system in +> general should consult upstream software documentation. Additionally, the Arch +> Wiki provides a fairly comprehensive outline of common Linux software +> configuration, and a variety of internet search engines are available for +> further assistance. + +Thus, we are unlikely to accept contributions which add information that is not +particularly Evolution-specific. + +## Style Guide + +This style guide outlines the standards for contributing to the Handbook. The +manual on is generated from an +[mdBook](https://rust-lang.github.io/mdBook/) stored in the +[evolution-docs](https://github.com/evolution-linux/evolution-docs/) repository. + +### General + +Although there will always be cases where command listings are appropriate, the +contents of the Handbook should be written in American English. + +Outside of the 'installation' sections, step-by-step instructions containing +'magic' commands for copying-and-pasting are strongly discouraged. Users are +expected to read the canonical documentation (e.g. man pages) for individual +programs to understand how to use them, rather than relying on +copying-and-pasting. + +Command code-blocks should not be used to describe routine tasks documented +elsewhere in this Handbook. For example, when writing documentation for the +`foo` package, do not provide a command code-block stating that one should +install it via `xbps-install foo`. Similarly, do not provide code blocks +describing how to enable the `foo` service. + +### Formatting + +For markdown formatting, the +[evolution-docs](https://github.com/evolution-linux/evolution-docs/) project uses the +[Versioned Markdown](https://github.com/bobertlo/vmd) format, and enforces use +of the auto-formatter `vmdfmt`, which works very similarly to `gofmt`. Most +valid markdown is accepted by the formatter. The output format is described in +the project's [README](https://github.com/bobertlo/vmd/blob/master/README.md). + +After installing the `vmdfmt` package, you can format a file by running: + +``` +vmdfmt -w +``` + +To format the entire mdbook from the repository root, outputting a list of files +modified, run: + +``` +vmdfmt -w -l +``` + +`vmdfmt` is used by the evolution-docs repository's `check.sh` script, which must be +[run locally before submitting a pull request](#making-changes). + +### Commands + +Command code-blocks should start with a `#` or `$` character, indicating whether +the command should be run as `root` or a regular user, respectively. + +For example: + +``` +# vi /etc/fstab +``` + +and not: + +``` +$ sudo vi /etc/fstab +``` + +and also not: + +``` +vi /etc/fstab +``` + +Command code-blocks should be introduced with a colon (':'), i.e.: + +> For example: +> +> `$ ls -l` + +#### Placeholders + +Placeholders indicate where the user should substitute the appropriate +information. They should use angle brackets (`<` and `>`) and contain only +lower-case text, with words separated by underscores. For example: + +``` +# ln -s /etc/sv/ /var/service/ +``` + +and not: + +``` +# ln -s /etc/sv/[SERVICENAME] /var/service/ +``` + +### Links + +Link text should not include sentence-level punctuation. For example: + +``` +[Visit this site](https://example.org). +``` + +and not: + +``` +[Visit this site.](https://example.org) +``` + +#### Internal links + +Links to other sections of the Handbook must be relative. For example: + +``` +[example](./example.md#heading-text) +``` + +and not: + +``` +[example](example.md#heading-text) +``` + +When referring literally to a Handbook section, the section title should be +placed in double-quotes. Otherwise, double-quotes are not required. For example: + +``` +For more information, please read the "[Power Management](./power-management.md)" section. +``` + +and + +``` +EvolutionOS provides facilities to assist with [power management](./power-management.md). +``` + +#### Man Page Links + +The first reference to a command or man page must be a link to the relevant man +page on `https://man.voidlinux.org/`. + +The link text must contain the title section number in parenthesis, and contain +no formatting. For example: [man(1)](https://man.voidlinux.org/man.1), not +[`man(1)`](https://man.voidlinux.org/man.1). + +#### Auto Links + +Auto links (links with the same title as URL) should use the following notation: + +``` + +``` + +They should not be formatted like this: + +``` +[https://www.example.com/](https://www.example.com/) +``` + +#### Checking links + +If you're including new links (either internal or external) in the docs or +changing the current file structure, you should make use of the +`mdbook-linkcheck` package: + +``` +$ mdbook-linkcheck -s +``` + +This will verify all the references, and warn you if there are any issues. If +any link you're using is correct but generating errors for some reason, you can +add its domain to the exclude list in `book.toml`, under the +`[mdbook.linkcheck]` key. + +`mdbook-linkcheck` is used by the evolution-docs repository's `check.sh` script, +which must be [run locally before submitting a pull request](#making-changes). + +#### Redirects + +When changing a section name, or moving a section to a different part of the +Handbook, a redirect must be added to the `[output.html.redirect]` section in +`book.toml`, e.g. + +``` +"/example.html" = "/new-location/example.html" +``` + +### Case + +Proper nouns outside of code blocks should use the casing of official +information sources: e.g. 'runit' not 'Runit', 'DKMS' not 'dkms', 'GRUB' not +'Grub' or 'grub', etc. In general, abbreviations should be upper-cased: 'CPU' +for central processing unit, 'SSD' for solid state drive, 'UI' for user +interface, etc. + +Handbook filenames and directories should use [kebab +case](https://en.wikipedia.org/wiki/Kebab_case) when splitting words. For +example the filename should be `post-install.md` not `postinstall.md`. Words +that are part of trademarks or well-known package names are exempt from this +rule: for example, `PulseAudio` and `NetworkManager` are well-known by their +[camel-case](https://en.wikipedia.org/wiki/Camel_case) names. + +### Voice + +Prefer the active imperative voice when writing documentation. Consider the +following examples: + +> Now we need to install the CUPS drivers and configure them. + +This version is conversational and friendlier, but contains unnecessary language +that may not be as clear to an ESL reader. + +> Install and configure the CUPS drivers, then configure them as shown. + +This version contains a clear command to act, and a follow up that shows what +will be done next. It is clear both to native English speakers, ESL readers, and +to translators. + +### Warnings + +Warnings should begin with `**Warning**:`, and should not be block-quoted with +`>`. For example, the Markdown should look like: + +``` +**Warning**: Selecting the wrong option will set your printer on fire. +``` + +and not: + +``` +> WARNING: Selecting the wrong option will set your printer on fire. +``` + +### Notes + +Notes should only be used sparingly, and for non-critical information. They +should begin with a phrase such as "Note that ..." or "It should be noted that +... ", and not be block-quoted with `>`. For example, the Markdown should look +like: + +``` +Note that you can also use program X for this purpose. +``` + +and not: + +``` +> You can also use program X for this purpose. +``` + +### Block quotes + +Block quotes (i.e. `>`) should only be used to quote text from an external +source. + +## Submitting Changes + +Proposed changes should be submitted as pull requests to the +[evolution-docs](https://github.com/evolution-linux/evolution-docs) repository on +[GitHub](https://github.com/). Please note that, unlike a wiki, submissions will +be reviewed before they are merged. If any changes are required they will need +to be made before the pull request is accepted. This process is in place to +ensure the quality and standards of the Handbook are sustained. + +### Requirements + +To clone the repository and push changes, +[git(1)](https://man.voidlinux.org/git.1) is required. It can be installed via +the `git` package. + +Building the Handbook locally requires +[mdBook](https://rust-lang.github.io/mdBook/), which can be installed via the +`mdBook` package. + +### Forking + +To fork the repository a [GitHub account](https://github.com/join) is needed. +Once you have an account, follow GitHub's +[guide](https://help.github.com/en/articles/fork-a-repo) on setting up a fork. + +Clone the repository onto your computer, enter it, and create a new branch: + +``` +$ git clone https://github.com//evolution-docs.git +$ cd evolution-docs +$ git checkout -b +``` + +You can then edit the repository files as appropriate. + +### Making changes + +To serve the docs locally and view your changes, run `mdbook serve` from the +root of the repository. + +Once you're satisfied with your changes, run the `check.sh` script provided in +the repository root. This will run the `vmdfmt` command, which will wrap the +text appropriately, and the `mdbook-linkcheck` command, which will check for +broken links. Address any issues raised by `check.sh`. + +Once `check.sh` runs without errors, push your changes to your forked +repository: + +``` +$ git add +$ git commit -m "" +$ git push --set-upstream origin +``` + +The commit message should be in the form `: `. + +Pull requests should only contain a single commit. If a change is made after the +initial commit, `git add` the changed files and then run `git commit --amend`. +The updated commit will need to be force-pushed: `git push --force`. + +If multiple commits are made they will need to be squashed into a single commit +with `git rebase -i HEAD~X`, where `X` is the number of commits that need to be +squashed. An editor will appear to choose which commits to squash. A second +editor will appear to choose the commit message. See +[git-rebase(1)](https://man.voidlinux.org/git-rebase.1) for more information. +The updated commit will need to be force-pushed: `git push --force`. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..66d28dc --- /dev/null +++ b/LICENSE @@ -0,0 +1,427 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md new file mode 100644 index 0000000..472041e --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ +# Evolution Docs + +Welcome to the EvolutionOS documentation. This repository contains the source data +behind . Contributing to this repository follows +the same protocol as the packages tree. For details, please read +[CONTRIBUTING](./CONTRIBUTING.md). + +## Building + +The [res/build.sh](./res/build.sh) script builds HTML, roff and PDF versions of +the EvolutionOS documentation and the `evolution-docs.1` man page. It requires the following +EvolutionOS packages: + +- `mdBook` +- `findutils` or `busybox + evolution-patches` +- `lowdown` (version 0.8.1 or greater) +- `texlive` +- `perl` +- `perl-File-Which` +- `perl-JSON` +- `librsvg-utils` +- `python3-md2gemini` + +In order to build and install these files, set the `PREFIX` and `DESTDIR` +environment variables to appropriate values and run `res/build.sh` followed by +`res/install.sh`. diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..6dae9d3 --- /dev/null +++ b/book.toml @@ -0,0 +1,36 @@ +[book] +authors = ["Tracker-Friendly"] +multilingual = false +src = "src" +title = "EvolutionOS Handbook" + +[output.html] +theme = "src/theme" + +[output.html.redirect] +"/about-this-handbook.html" = "/about/about-this-handbook.html" +"/config/man.html" = "/config/package-documentation/man.html" +"/config/gnupg.html" = "/config/openpgp.html#gnupg" + +[output.latex] +optional = true + +[output.gemini] +optional = true + +[output.linkcheck] +optional = true +follow-web-links = true +exclude = [ + 'kernel\.org', + 'ntp\.org', + '\.onion', + 'localhost', + 'userbase\.kde\.org', + 'sjtu\.edu\.cn', + 'mirrors\.cnnic\.cn', + 'void\.webconverger\.org', + 'mirror\.vofr\.net', + 'void\.chililinux\.com', + 'voidlinux\.com\.br', +] diff --git a/check.sh b/check.sh new file mode 100755 index 0000000..9a77d43 --- /dev/null +++ b/check.sh @@ -0,0 +1,71 @@ +#!/bin/sh + +# reset variable so it doesn't use the environment one +MISSING= + +echo -n "Checking for mdbook-linkcheck ... " +if ! command -v mdbook-linkcheck; then + MISSING="$MISSING mdbook-linkcheck" + echo "not found" +fi + +echo -n "Checking for vmdfmt ... " +if ! command -v vmdfmt; then + MISSING="$MISSING vmdfmt" + echo "not found" +fi + +if [ "$MISSING" ]; then + + echo -n "Checking for xbps-install ... " + if ! command -v xbps-install; then + echo "not found" + echo "Please manually install: $MISSING" + exit 1 + fi + + echo -n "Checking for sudo ... " + if command -v sudo; then + SU_CMD='sudo' + else + echo "not found" + echo "Checking for doas ... " + if command -v doas; then + SU_CMD='doas' + else + echo "not found" + "Please manually install: $MISSING" + exit 1 + fi + fi + + echo "\nTrying to install ${MISSING## } ... " + $SU_CMD xbps-install $MISSING + echo + + # Check whether executables are now present. + + for i in $MISSING; do + if ! command -v $i 2>&1 >/dev/null; then + UNAVAILABLE="$UNAVAILABLE $i" + fi + done + + if [ "$UNAVAILABLE" ]; then + echo "Can't proceed without: ${UNAVAILABLE## }. Aborting." + exit 1 + fi + +fi + +vmdfmt -l -w src/ + +if command -v mdbook 2>&1 >/dev/null; then + echo "Building book and checking links with mdbook ..." + mdbook build +else + echo "Checking links with mdbook-linkcheck ..." + mdbook-linkcheck -s +fi + +echo "Checks completed." diff --git a/res/README.md b/res/README.md new file mode 100644 index 0000000..7031b51 --- /dev/null +++ b/res/README.md @@ -0,0 +1,2 @@ +The original cover variants, as suggested by @argosatcore on GitHub, +are available in the `handbook-cover-variants.svg` file. diff --git a/res/build.sh b/res/build.sh new file mode 100755 index 0000000..22f3a75 --- /dev/null +++ b/res/build.sh @@ -0,0 +1,92 @@ +#!/bin/sh +# uses PREFIX and BUILD_MANPAGES from environment +: "${PREFIX:=/usr/local}" +: "${BUILD_MANPAGES:=1}" + +set -e +PATH="$PWD/res:$PATH" + +if [ -z "$SOURCE_DATE_EPOCH" ]; then + export SOURCE_DATE_EPOCH=$(git log --pretty='%ct' -1) + if [ -z "$SOURCE_DATE_EPOCH" -a "$BUILD_MANPAGES" = 1 ]; then + echo "git or SOURCE_DATE_EPOCH are needed to build man pages!" + exit 1 + fi +fi + +# Build HTML mdbook +echo "Building mdBook" +mdbook build + +if [ "$BUILD_MANPAGES" = "1" ]; then + # Build mandoc version + echo "Building man pages" + cd src + + find . -type d -exec mkdir -p "../mandoc/{}" \; + + find . -type f -name "*.md" -exec sh -c \ + 'file="{}"; filew="${file%.md}"; \ + man_date="$(git log --pretty=%cs -1 "$file" 2>/dev/null || date -d "@$SOURCE_DATE_EPOCH" +%F)"; + lowdown -Tman \ + ${man_date:+-m "date: $man_date"} \ + -m "title: ${filew##*/}" \ + -m "section: 7" -m "source: Void Docs" -m "volume: Void Docs" \ + -s -o "../mandoc/${filew}.7" "$file"' \; + + cd - +fi + +# Build script +echo "Building void-docs script and man page" +sed -e "s,@PREFIX@,$PREFIX," res/void-docs.in > res/void-docs +sed -e "s,@PREFIX@,$PREFIX," res/void-docs.1.in > res/void-docs.1 + +# Build PDF + +echo "Building PDF" + +## Temporarily add OpenType version of Latin Modern to font cache. + +mkdir -p ~/.fonts +TMP_FONTDIR=$(mktemp -d -p ~/.fonts) +cp /usr/share/texmf-dist/fonts/opentype/public/lm/* $TMP_FONTDIR +fc-cache + +## Create cover page using Latin Modern text. + +rsvg-convert \ + --dpi-x 300 \ + --dpi-y 300 \ + res/handbook-cover.svg > res/handbook-cover.png + +## Letter version + +pdflatex \ + -output-directory=book/latex/ \ + -jobname=handbook-letter \ + book/latex/handbook.tex \ + >/dev/null +pdflatex \ + -output-directory=book/latex/ \ + -jobname=handbook-letter \ + book/latex/handbook.tex \ + >/dev/null + +## A4 version + +sed -ie "s/\\documentclass\[letterpaper\]{article}/\\documentclass[a4paper]{article}/" \ + book/latex/handbook.tex +pdflatex -output-directory=book/latex/ \ + -jobname=handbook-a4 \ + book/latex/handbook.tex \ + >/dev/null +pdflatex -output-directory=book/latex/ \ + -jobname=handbook-a4 \ + book/latex/handbook.tex \ + >/dev/null + +## Remove temporary font directory + +rm -rf $TMP_FONTDIR +fc-cache diff --git a/res/ci/check-summary.sh b/res/ci/check-summary.sh new file mode 100755 index 0000000..1895973 --- /dev/null +++ b/res/ci/check-summary.sh @@ -0,0 +1,22 @@ +#!/bin/sh + +ERROR=0 + +printf "\n\033[37;1m=> Checking SUMMARY.md\033[m\n" + +cd src/ || exit 2 + +# summary is the list of files taken from SUMMARY.md - unused for now +summary="$( sed -e '/(/!d' -e 's/.*(//' -e 's/)//' ./SUMMARY.md )" + +files="$( find . -type f -name '*.md' -not -name "SUMMARY.md" )" + +for file in $files +do + if ! grep -q "$file" ./SUMMARY.md ; then + printf "::error title=Summary Lint,file=src/SUMMARY.md::$file not in SUMMARY.md\n" + ERROR=1 + fi +done + +exit $ERROR diff --git a/res/ci/commit-lint.sh b/res/ci/commit-lint.sh new file mode 100755 index 0000000..f6b7753 --- /dev/null +++ b/res/ci/commit-lint.sh @@ -0,0 +1,46 @@ +#!/bin/sh + +die() { + printf '%s\n' "$*" >&2 + exit 1 +} + +command -v git >/dev/null 2>&1 || +die "neither chroot-git nor git could be found!" + +tip="$(git rev-list -1 --parents HEAD)" +case "$tip" in + # This is a merge commit, pick last parent + *" "*" "*) tip="${tip##* }" ;; + # This is a non-merge commit, pick itself + *) tip="${tip%% *}" ;; +esac + +base="$(git merge-base origin/HEAD "$tip")" + +[ $(git rev-list --count "$tip" "^$base") -lt 20 ] || { + echo "::error title=Branch out of date::Your branch is too out of date. Please rebase on upstream and force-push." + exit 1 +} + +status=0 + +for cmt in $(git rev-list --abbrev-commit $base..$tip) +do + git cat-file commit "$cmt" | + awk -vC="$cmt" ' + # skip header + /^$/ && !msg { msg = 1; next } + !msg { next } + # 3: long-line-is-banned-except-footnote-like-this-for-url + (NF > 2) && (length > 80) { print "::error title=Commit Lint::" C ": long line: " $0; exit 1 } + !subject { + if (length > 50) { print "::warning title=Commit Lint::" C ": subject is a bit long" } + if (!($0 ~ ":")) { print "::error title=Commit Lint::" C ": subject does not follow CONTRIBUTING.md guidelines"; exit 1 } + subject = 1; next + } + /^$/ { body = 1; next } + !body { print "::error title=Commit Lint::" C ": second line must be blank"; exit 1 } + ' || status=1 +done +exit $status diff --git a/res/ci/format.sh b/res/ci/format.sh new file mode 100755 index 0000000..7ed3e8d --- /dev/null +++ b/res/ci/format.sh @@ -0,0 +1,15 @@ +#!/bin/sh + +printf "\n\033[37;1m=> Formatting tree\033[m\n" +vmdfmt -l -w src/ + +# Check Status +if [ ! -z "$(git status --porcelain)" ] ; then + git diff --color=always + printf "\033[31;1m=> Files which need to be formatted:\033[m\n" + for f in $(git status | grep -Po 'modified:\K.*$'); do + printf "$f\n" + printf "::error title=Formatting Lint,file=$f,line=1::File has improper formatting\n" + done + exit 1 +fi diff --git a/res/ci/linkcheck.sh b/res/ci/linkcheck.sh new file mode 100755 index 0000000..8da6d9a --- /dev/null +++ b/res/ci/linkcheck.sh @@ -0,0 +1,11 @@ +#!/bin/sh + +# only show all the debug messages if ci is run with debug +if [ "$RUNNER_DEBUG" ]; then + loglevel=debug +else + loglevel=error +fi + +printf "\033[37;1m=> Checking links\033[m\n" +RUST_LOG="linkcheck=$loglevel" mdbook-linkcheck -s -c always diff --git a/res/handbook-cover-variants.svg b/res/handbook-cover-variants.svg new file mode 100644 index 0000000..52d164f --- /dev/null +++ b/res/handbook-cover-variants.svg @@ -0,0 +1,1121 @@ + +image/svg+xmlEvolutionOS is a general purpose operating system, based on the monolithic Linux® kernel. Its package system allows you to quickly install, update and remove software; software is provided in binary packages or can be built directly from sources with the help of the XBPS source packages collection. EvolutionOS is a general purpose operating system, based on the monolithic Linux® kernel. Its package system allows you to quickly install, update and remove software; software is provided in binary packages or can be built directly from sources with the help of the XBPS source packages collection. EvolutionOS HandbookEvolutionOS HandbookEvolutionOS HandbookEvolutionOS is a general purpose operating system, based on the monolithic Linux® kernel. Its package system allows you to quickly install, update and remove software; software is provided in binary packages or can be built directly from sources with the help of the XBPS source packages collection. EvolutionOS is a general purpose operating system, based on the monolithic Linux® kernel. Its package system allows you to quickly install, update and remove software; software is provided in binary packages or can be built directly from sources with the help of the XBPS source packages collection. EvolutionOS is a general purpose operating system, based on the monolithic Linux® kernel. Its package system allows you to quickly install, update and remove software; software is provided in binary packages or can be built directly from sources with the help of the XBPS source packages collection. EvolutionOS is a general purpose operating system, based on the monolithic Linux® kernel. Its package system allows you to quickly install, update and remove software; software is provided in binary packages or can be built directly from sources with the help of the XBPS source packages collection. EvolutionOS HandbookEvolutionOS HandbookEvolutionOS Handbook diff --git a/res/handbook-cover.svg b/res/handbook-cover.svg new file mode 100644 index 0000000..b05fc45 --- /dev/null +++ b/res/handbook-cover.svg @@ -0,0 +1,502 @@ + +image/svg+xmlEvolutionOS HandbookEvolutionOS is a general purpose operating system, based onthe monolithic Linux kernel. Its package systemallows you to quickly install, update and removesoftware; software is provided in binary packages orcan be built directly from sources with the help of the XBPS source packages collection. diff --git a/res/install.sh b/res/install.sh new file mode 100755 index 0000000..9142db9 --- /dev/null +++ b/res/install.sh @@ -0,0 +1,19 @@ +#!/bin/sh +# uses PREFIX and DESTDIR from environment +: "${PREFIX:=/usr/local}" + +set -e + +DOC=${DESTDIR}${PREFIX}/share/doc/void +mkdir -p $DOC/ + +cp -r src/ $DOC/markdown +rm -fr $DOC/markdown/theme + +cp -r book/html $DOC/html + +cp -r mandoc/ $DOC/mandoc + +install -Dm0644 res/void-docs.1 ${DESTDIR}${PREFIX}/share/man/man1/void-docs.1 +install -Dm0755 res/void-docs ${DESTDIR}${PREFIX}/bin/void-docs +install -Dm0644 book/latex/handbook-a4.pdf ${DESTDIR}${PREFIX}/share/doc/void/handbook.pdf diff --git a/res/mdbook-gemini b/res/mdbook-gemini new file mode 100755 index 0000000..80f3c1b --- /dev/null +++ b/res/mdbook-gemini @@ -0,0 +1,123 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +use File::Which; +use File::Path qw(make_path); +use JSON; + +# Accept input on stdin regardless of whether the 'md2gemini' executable +# is present, to avoid "Broken pipe" errors from mdBook. + +my $data; +{ + local $/; + undef $/; + $data = <>; +} + +if (! defined which 'md2gemini') { + print "'md2gemini' not found in PATH; not building Gemini output\n"; + # We can't return non-zero here, as that would cause the entire + # mdBook build process to fail. + exit 0; +} + +my $json = JSON->new->decode($data); +my $sections = $json->{book}->{sections}; + +# Create toc.gmi from SUMMARY.md + +my $leader; + +open(my $summary, '<', '../../src/SUMMARY.md') + or die "Can't open SUMMARY.md for reading: $!\n"; +open(my $toc, '>', 'toc.gmi') + or die "Can't open toc.gmi for writing: $!\n"; + +print $toc "# Table of Contents\n\n"; +while (<$summary>) { + + if (/^(\s*)- \[([^\]]+)\]\(([^\)]+)\)/) { + + my $depth = $1; + my $heading = $2; + my $path = $3; + + if (length($depth) == 0) { + $leader = '-'; + } else { + $leader = '-' x (1 + (length($depth) / 3)); + } + + $path =~ s/\.md$/.gmi/; + + print $toc "=> " . $path . " " . $leader . " " . $heading . "\n"; + + } + +} + +close($summary) + or die "Can't close SUMMARY.md after reading: $!\n"; +close($toc) + or die "Can't close toc.gmi after writing: $!\n"; + +# Create individual pages. + +foreach my $i (@$sections) { + process_json($i); +} + +exit 0; + + +### Functions + +sub process_json { + + my $i = shift; + my $type = ref($i); + if ($type eq 'HASH') { + if (defined $i->{content}) { + process_content($i->{path},$i->{content}); + } + if (defined $i->{Chapter}) { + process_json($i->{Chapter}); + } + if (defined $i->{sub_items}) { + foreach my $j ($i->{sub_items}) { + process_json($j); + } + } + } + if ($type eq 'ARRAY') { + foreach my $j (@{$i}) { + process_json($j); + } + } +} + +sub process_content { + + my $path = shift; + my $directory = $path; + my $filename = $path; + my $content = shift; + my $fh; + + $directory =~ s|/[^/]+\.md$||; + $filename =~ s|^.*/([^/]+)\.md$|$1.gmi|; + + make_path($directory); + + open($fh, "| md2gemini --links copy --md-links --ascii-table > " . + $directory . '/' . $filename) + or die "Can't open pipe to md2gemini: $!\n"; + print $fh $content; + print $fh "\n\n" . "=> /toc.gmi Table of Contents" . "\n"; + close $fh + or die "Can't close pipe to md2gemini: $!\n"; + +} diff --git a/res/mdbook-latex b/res/mdbook-latex new file mode 100755 index 0000000..1c96000 --- /dev/null +++ b/res/mdbook-latex @@ -0,0 +1,389 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +use Cwd; +use JSON; + +my $data; +{ + local $/; + undef $/; + $data = <>; +} +my $json = JSON->new->decode($data); +my $sections = $json->{book}->{sections}; + +my $date = `date '+%d %B %Y'`; +chomp $date; + +my $latex; +my %code_inline; +my $code_inline_index = 0; +my %codeblocks; +my $codeblock_index = 0; + +# Opening. + +$latex .= "\\documentclass[letterpaper]{article}\n"; +$latex .= "\\usepackage[margin=4cm]{geometry}\n"; +$latex .= "\\usepackage[T1]{fontenc}\n"; +$latex .= "\\fontfamily{lmodern}\n"; +$latex .= "\\selectfont\n"; +$latex .= "\\usepackage{graphicx}\n"; +$latex .= "\\usepackage{hyperref}\n"; +$latex .= "\\usepackage{listings}\n"; +$latex .= "\\lstdefinestyle{void}{\n"; +$latex .= " basicstyle=\\ttfamily,\n"; +$latex .= " breaklines=true,\n"; +$latex .= " showstringspaces=false,\n"; +$latex .= " aboveskip=\\bigskipamount,\n"; +$latex .= " belowskip=\\bigskipamount,\n"; +$latex .= "}\n"; +$latex .= "\\def\\code#1{\\texttt{#1}}\n"; +$latex .= "\\begin{document}\n"; +$latex .= "\\newgeometry{margin=2cm}\n"; +$latex .= "\\begin{titlepage}\n"; +$latex .= " \\includegraphics[width=160mm,height=230mm]{res/handbook-cover.png}\n"; +$latex .= "\\end{titlepage}\n"; +$latex .=" \\restoregeometry\n"; +$latex .= "\\title{EvolutionOS Handbook}\n"; +$latex .= "\\date{$date}\n"; +$latex .= "\\maketitle\n"; +$latex .= "\\setcounter{tocdepth}{5}\n"; +$latex .= "\\tableofcontents\n"; +$latex .= "\\begin{sloppypar}\n"; # Ugly; need to find better solution + +# Contents. + +foreach my $i (@$sections) { + process_json($i); +} + +# Postprocessing. + +$latex =~ s/config-network-wpa\\_supplicant/config-network-wpa_supplicant/g; +$latex =~ s/config-network-wpa_supplicant-the-wpa\\_supplicant-service/config-network-wpa_supplicant-the-wpa_supplicant-service/g; +$latex =~ s/(handbook-codeblock-\d+)/$codeblocks{$1}/eg; +$latex =~ s/(handbook-codeinline-\d+)/$code_inline{$1}/eg; + +# Closing. + +$latex .= "\\end{sloppypar}\n"; +$latex .= "\\end{document}\n"; + +open(my $fh, ">", "handbook.tex") + or die "Can't open handbook.tex for writing: $!"; +print $fh $latex; +close($fh) + or die "Couldn't close handbook.tex after writing: $!"; + +exit 0; + +sub process_json { + + my $i = shift; + my $type = ref($i); + if ($type eq 'HASH') { + if (defined $i->{content}) { + process_content($i->{path},$i->{content}); + } + if (defined $i->{Chapter}) { + process_json($i->{Chapter}); + } + if (defined $i->{sub_items}) { + foreach my $j ($i->{sub_items}) { + process_json($j); + } + } + } + if ($type eq 'ARRAY') { + foreach my $j (@{$i}) { + process_json($j); + } + } +} + +sub process_content { + + my $path = shift; + my $content = shift; + my $base = convert_path_to_hypertarget_base($path); + + # Create sections. + $content =~ s/^# ([^\n]+)/create_sectioning("section",$1,$base)/eg; + + # Create subsections. + $content =~ s/\n## ([^\n]+)/create_sectioning("subsection",$1,$base)/eg; + + # Create subsubsections. + $content =~ s/\n### ([^\n]+)/create_sectioning("subsubsection",$1,$base)/eg; + + # Create paragraphs. + $content =~ s/\n#### ([^\n]+)/create_sectioning("paragraph",$1,$base)/eg; + + # Create subparagraphs. + $content =~ s/\n##### ([^\n]+)/create_sectioning("subparagraph",$1,$base)/eg; + + # Create codeblocks. + $content =~ s/```\n(.+?)\n```/create_codeblock($1)/esg; + + # Create internal links. + $content =~ s/\[([^]]+?)\]\(((?:\..?.+?)|(?:#.+?))\)/create_internal_link($1,$2,$path)/esg; + + # Create external links. + $content =~ s/<(http[^>]+)>/\\href{$1}{$1}/sg; # bare links + $content =~ s/\[([^]]+?)\]\((.+?)\)/\\href{$2}{$1}/sg; + + # Create lists. + $content =~ s/\n\n(- .+?)\n(?:\n|\z)/create_list($1)/esg; + + # Create numbered lists. + $content =~ s/\n\n(\d+\. .+?)\n(?:\n|\z)/create_numbered_list($1)/esg; + + # Create blockquotes. + $content =~ s/((^>(?:\s*\n|[^\n]+))+)/create_blockquote($1)/emsg; + + # Bold text. + $content =~ s/\*\*([^*]+)\*\*/{\\bfseries $1}/sg; + + # Escape LaTeX special characters. + $content =~ s/#/'\#'/eg; + $content =~ s/\$/'\$'/eg; + $content =~ s/_/'\_'/eg; + $content =~ s/~/'\~'/eg; + $content =~ s/&/'\&'/eg; + $content =~ s/\^/'\^'/eg; + + # Create tables. + $content =~ s/((?:(?:\| +[^|]+ +\| +(?:[^|]+ +\|)+\n)|(?:\|-[^\n]+\n))+)/create_table($1)/esg; + + # Create inline code. + $content =~ s/(?: |\n)`([^`]+)`/create_code_inline($1)/esg; + + $latex .= $content; + +} + +sub convert_heading_to_fragment { + + my $heading = shift; + + $heading =~ s/ /-/g; + $heading =~ s/\.//g; + $heading =~ s/\(|\)//g; + $heading =~ s/(.+)/lc($1)/e; + + return $heading; + +} + +sub convert_path_to_hypertarget_base { + + my $base = shift; + + if ($base =~ m|index.md|) { + $base =~ m|(.+/index).md|; + $base = $1; + $base =~ s|/|-|g; + } else { + $base =~ m|(.+).md|; + $base = $1; + $base =~ s|/|-|g; + } + + return $base; + +} + +sub create_blockquote { + + my $blockquote = shift; + my $result; + + $blockquote =~ s/>//g; + $blockquote =~ s/\n//g; + + $result .= "\\begin{quote}\n"; + $result .= $blockquote; + $result .= "\\end{quote}\n"; + + return $result; + +} + +sub create_codeblock { + + my $codeblock = shift; + my $label; + my $result; + + $codeblock_index++; + $label = 'handbook-codeblock-' . $codeblock_index; + + $result .= "\\begin{lstlisting}[style=void]\n"; + $result .= $codeblock; + $result .= "\n\\end{lstlisting}\n"; + + $codeblocks{$label} = $result; + + # Mark places in document where codeblock will be re-inserted + # during postprocessing. + return $label; + +} + +sub create_code_inline { + + my $code = shift; + my $label; + my $result; + + $code_inline_index++; + $label = 'handbook-codeinline-' . $code_inline_index; + + $result = " \\code{$code}"; + + $code_inline{$label} = $result; + + # Mark places in document where code will be re-inserted + # during postprocessing. + return $label; + +} + +sub create_internal_link { + + my $text = shift; + my $destination = shift; + my $current_section = shift; + my $current_directory; + my $base; + my $fragment; + my $hypertarget; + my $result; + + if ($destination =~ /^#/) { + $base = $current_section . $destination; + $base =~ s|.md#.+$||; + } else { + $current_section =~ m|^(.+/)|; + $current_directory = $1; + $base = $destination; + $base =~ m|^(.+\.md)|; + $base = $1; + $base = $current_directory . $base; + $base = Cwd::abs_path("../../src/" . $base); + $base =~ s|^.+/src/||; + $base =~ s|.md||; + } + $base =~ s|/|-|g; + + if ($destination =~ /#/) { + $destination =~ m|#(.+)$|; + $fragment = "-" . $1; + } else { + $fragment = ""; + } + + $text =~ s/\n/ /; + $hypertarget = $base . $fragment; + $result = "\\hyperlink{$hypertarget}{$text}"; + + return $result; + +} + +sub create_list { + + my $list = shift; + my $result; + + $result .= "\n\\begin{itemize}\n"; + $list =~ s/^- /\\item /mg; + $result .= $list; + $result .= "\n\\end{itemize}\n"; + + return $result; + +} + +sub create_numbered_list { + + my $list = shift; + my $result; + + $result .= "\n\\begin{enumerate}\n"; + $list =~ s/^\d+\. /\\item /mg; + $result .= $list; + $result .= "\n\\end{enumerate}\n"; + + return $result; + +} + +sub create_sectioning { + + my $type = shift; + my $text = shift; + my $name = shift; + my $result; + + if ($type ne "section") { + $name = $name . "-" . convert_heading_to_fragment($text); + $result .= "\n\\hypertarget{"; + $result .= $name; + $result .= "}{}"; + $result .= "\n\\$type\{$text\}\n"; + } else { + $result .= "\n\\newpage\n"; + $result .= "\n\\hypertarget{"; + $result .= $name; + $result .= "}{}"; + $result .= "\n\\$type\{$text\}\n"; + } + + return $result; + +} + +sub create_table { + + my $table = shift; + my $result; + my @lines; + my $header; + my @body; + my $column_count; + + @lines = split(/\n/, $table); + $header = $lines[0]; + $header =~ s/[^|]//g; + $column_count = length($header) - 1; + + $result .= "\n\\bigskip"; + $result .= "\n\\begin{tabular}{ | "; + $result .= "l | " x ($column_count - 1); + $result .= "l | }\n"; + $result .= "\\hline\n"; + $header = $lines[0]; + $header =~ s/^\|//; + $header =~ s/\|/&/g; + $header =~ s/&$//; + $result .= $header; + $result .= "\\\\ \\hline \\hline\n"; + shift @lines; + foreach my $line (@lines) { + if ($line !~ /^\|-/) { + $line =~ s/^\|//; + $line =~ s/\|/&/g; + $line =~ s/&$//; + $result .= $line; + $result .= "\\\\ \\hline\n"; + } + } + $result .= "\n\\end{tabular}\n"; + $result .= "\n\\bigskip\n"; + +} diff --git a/res/void-docs.1.in b/res/void-docs.1.in new file mode 100644 index 0000000..2ef149e --- /dev/null +++ b/res/void-docs.1.in @@ -0,0 +1,190 @@ +.Dd October 09, 2020 +.Dt VOID-DOCS 1 +.Os +.Sh NAME +.Nm void-docs +.Nd Access Void Linux documentation +.Sh SYNOPSIS +.Nm +.Op OPTIONS +.Op search terms +.Sh DESCRIPTION +The +.Nm +utility will attempt to launch different programs until it can find an +adequate one to display the Void Linux documentation. If it is invoked +without a search term, it will show the documentation's home +page. Multiple search terms can be used to filter results. If the user +has the +.Xr fzf 1 +or +.Xr sk 1 +utilities installed in their system, it will be used to browse the +results. Otherwise, +.Nm +will immediately display the first search result. If the +.Fl s +flag is used, +.Nm +will display the search results instead of the documentation. + +The programs +.Nm +will try to use are, in order of preference: +.Bl -dash +.It +For the HTML version: +.Bl -dash +.It +the program specified in the environment variable +.Ev BROWSER . +.It +.Xr xdg-open 1 +if either the +.Ev DISPLAY +or +.Ev WAYLAND_DISPLAY +environment variable is set. +.It +.Xr run-mailcap 1 . +.It +the TUI browsers +.Xr lynx 1 , +.Xr w3m 1 , +and +.Xr links 1 . +.El +.It +For the Markdown version: +.Bl -dash +.It +the Markdown processors +.Sq mdcat +and +.Sq glow . +.El +.It +For the roff (mdoc) version: +.Bl -dash +.It +.Xr man 1 . +.El +.It +For the PDF version: +.Bl -dash +.It +.Xr xdg-open 1 , +and +.Xr run-mailcap 1 . +.It +the PDF viewers +.Xr zathura 1 +and +.Xr okular 1 . +.El +.El +.Pp +It should be noted that for the PDF version, +.Nm +doesn't support search results. +.Pp +For a better browsing experience, installing +.Xr fzf 1 +is recommended. +.Sh OPTIONS +.Bl -tag -width -x +.It Fl h, Fl -help +Show help message. +.It Fl b +Only try to display the HTML version. +.It Fl m +Only try to display the Markdown version. +.It Fl r +Only try to display the roff (mdoc) version. +.It Fl p +Open the PDF version. +.It Fl s +Only display search results. +.El +.Sh FILES +The +.Sq void-docs +package contains a snapshot of the online documentation from +.Lk https://docs.voidlinux.org , +which intends to document installation, configuration and system +management for Void Linux. It is packaged in four formats. +.Bl -tag -width x +.It Pa @PREFIX@/share/doc/void/html +Documentation in HTML format. Can be viewed with any browser, such as +Mozilla Firefox or Chromium. Recommended when a GUI session is +available, because it allows easy navigation between the documentation +pages and has the same format as the official website. Can be accessed +by pointing a browser to +.Pa @PREFIX@/share/doc/void/html/index.html . +.It Pa @PREFIX@/share/doc/void/markdown +Documentation in Markdown format. Can be viewed as text files, using +.Xr cat 1 +or +.Xr less 1 , +or as formatted Markdown files, using applications such as +.Sq mdcat +or +.Sq glow . +The table of contents can be accessed via the +.Pa @PREFIX@/share/doc/void/markdown/SUMMARY.md +file. +.It Pa @PREFIX@/share/doc/void/mandoc +Documentation in roff (mdoc) format. Can be viewed using +.Xr mandoc 1 . +Using +.Xr mandoc 1 +with the +.Fl a +option, which enables a pager, is recommended. +.It Pa @PREFIX@/share/doc/void/handbook.pdf +Documentation in PDF format. Can be viewed with any PDF viewer, such as +.Xr zathura 1 +or +.Xr okular 1 . +.Sh EXAMPLES +View the documentation page about the kernel: +.Pp +.Dl $ void-docs kernel +.Pp +View a documentation page inside another session: +.Pp +.Dl $ void-docs graphical-session kde +.Pp +View the homepage of the HTML documentation with +.Xr qutebrowser 1 : +.Pp +.Dl $ qutebrowser @PREFIX@/share/doc/void/html/index.html +.Pp +View the summary of the Markdown documentation with +.Xr less 1 : +.Pp +.Dl $ less @PREFIX@/share/doc/void/markdown/SUMMARY.md +.Pp +View the +.Dq Kernel +page of the Markdown documentation with +.Sq mdcat : +.Pp +.Dl $ mdcat @PREFIX@/share/doc/void/markdown/config/kernel.md +.Pp +View the +.Dq Cron +page of the roff (mdoc) documentation with +.Xr mandoc 1 : +.Pp +.Dl $ mandoc -a @PREFIX@/share/doc/void/mandoc/config/cron.7 +.Pp +.Sh AVAILABILITY +This man page is part of the void-docs package and is available from +.Lk https://github.com/void-linux/void-docs . +.Sh BUGS +The Void Linux documentation tries to limit itself to content that is +specific to Void. Therefore, if you feel something is missing, it +might have been deliberate. However, if there is any information that +is mistaken, outdated or indeed missing, please report an issue at +.Lk https://github.com/void-linux/void-docs . diff --git a/res/void-docs.in b/res/void-docs.in new file mode 100644 index 0000000..15154af --- /dev/null +++ b/res/void-docs.in @@ -0,0 +1,181 @@ +#!/bin/sh +# This is the void linux documentation browser + +[ "$DEBUG" ] && set -x +# turn on errors and noglob +set -fe + +# document to open +VOIDDOC= +# terms to search for +TERMS= +# versions to try +_html=1 +_md=1 +_roff=1 +_pdf= + +usage() { + cat <dev/null; then + exec $PDF_VIEWER $PDF + elif command -v xdg-open >/dev/null; then + exec xdg-open $PDF + elif command -v run-mailcap >/dev/null; then + exec run-mailcap --action=view $PDF + else + for cmd in zathura okular evince + do + if command -v $cmd >/dev/null; then + exec $cmd $PDF + fi + done + fi +fi + +# creates the appropriate path +find_page() { + case $1 in + html) VOIDDOC="$DOCS/html/$2.html" ;; + md) VOIDDOC="$DOCS/markdown/$2.md" ;; + man) VOIDDOC="$DOCS/mandoc/$2.7" ;; + esac + + if [ -f "$VOIDDOC" ]; then + echo "$VOIDDOC" + else + echo "couldn't find file" >&2 + return 1 + fi +} + +# knows how to open a certain page +open_page() { + if [ "$_html" ]; then + if [ -n "$BROWSER" ] && command -v $BROWSER >/dev/null; then + page=$(find_page html $1) + exec $BROWSER $page + fi + + # check if wayland or X session + if [ -n "$WAYLAND_DISPLAY" -o -n "$DISPLAY" ] && command -v xdg-open >/dev/null; then + page=$(find_page html $1) + exec xdg-open $page + fi + + if command -v run-mailcap >/dev/null; then + exec run-mailcap --action=view $PDF + fi + + # if a browser or xdg-open weren't available, we can try other stuff + + # cli browser + for viewer in lynx w3m links + do + if command -v $viewer >/dev/null; then + page=$(find_page html $1) + exec $viewer $page + fi + done + fi + + if [ "$_md" ]; then + # markdown processor + _viewer= + if command -v mdcat >/dev/null; then + _viewer=mdcat + elif command -v lowdown >/dev/null; then + _viewer="lowdown -Tterm" + elif command -v glow >/dev/null; then + _viewer=glow + fi + if [ "$_viewer" ]; then + page=$(find_page md $1) + $_viewer $page | less -R + exit + fi + fi + + if [ "$_roff" ]; then + # otherwise go for the man page + page=$(find_page man $1) + exec man -l $page + fi + + echo "Couldn't find a program to display the documentation." + return 1 +} + +search_page() { + file="$(find $DOCS/markdown -type f $1 -printf "%P\n")" + [ -z "$file" ] && exit 1 + + if [ "$_search" ]; then + echo "$file" + return 0 + fi + + _pager="head -1" + if command -v fzf >/dev/null; then + _pager=fzf + elif command -v sk >/dev/null; then + _pager=sk + elif command -v pick >/dev/null; then + _pager=pick + fi + + if [ $(IFS=' '; echo $file | wc -l) -gt 1 ]; then + file="$(echo "$file" | $_pager)" + fi + file="${file%.md}" + echo "$file" +} + +page=about/index +[ "$TERMS" ] && page="$(search_page "$TERMS")" + +if [ "$_search" ]; then + echo "$page" + exit 0 +fi + +open_page "$page" diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..3133a86 --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,86 @@ +# Summary + +- [About](./about/index.md) + - [History](./about/history.md) + - [About This Handbook](./about/about-this-handbook.md) + - [InfraDocs](./about/infradocs.md) +- [Installation](./installation/index.md) + - [Live Installers](./installation/live-images/index.md) + - [Prepare Installation Media](./installation/live-images/prep.md) + - [Partitioning Notes](./installation/live-images/partitions.md) + - [Installation Guide](./installation/live-images/guide.md) + - [Advanced Installation Guides](./installation/guides/index.md) + - [Installation via chroot + (x86/x86_64/aarch64)](./installation/guides/chroot.md) + - [Full Disk Encryption](./installation/guides/fde.md) + - [Root on ZFS](./installation/guides/zfs.md) + - [ARM Devices](./installation/guides/arm-devices/index.md) + - [Supported Platforms](./installation/guides/arm-devices/platforms.md) + - [musl](./installation/musl.md) +- [Configuration](./config/index.md) + - [Package Documentation](./config/package-documentation/index.md) + - [Manual Pages](./config/package-documentation/man.md) + - [Firmware](./config/firmware.md) + - [Locales and Translations](./config/locales.md) + - [Users and Groups](./config/users-and-groups.md) + - [Services and Daemons - runit](./config/services/index.md) + - [Per-User Services](./config/services/user-services.md) + - [Logging](./config/services/logging.md) + - [rc.conf, rc.local and rc.shutdown](./config/rc-files.md) + - [Cron](./config/cron.md) + - [Solid State Drives](./config/ssd.md) + - [Security](./config/security/index.md) + - [AppArmor](./config/security/apparmor.md) + - [Date and Time](./config/date-time.md) + - [Kernel](./config/kernel.md) + - [Power Management](./config/power-management.md) + - [Network](./config/network/index.md) + - [Firewalls](./config/network/firewalls.md) + - [wpa_supplicant](./config/network/wpa_supplicant.md) + - [IWD](./config/network/iwd.md) + - [NetworkManager](./config/network/networkmanager.md) + - [ConnMan](./config/network/connman.md) + - [Network Filesystems](./config/network-filesystems.md) + - [Session and Seat Management](./config/session-management.md) + - [Graphical Session](./config/graphical-session/index.md) + - [Graphics Drivers](./config/graphical-session/graphics-drivers/index.md) + - [AMD or ATI](./config/graphical-session/graphics-drivers/amd.md) + - [Intel](./config/graphical-session/graphics-drivers/intel.md) + - [NVIDIA](./config/graphical-session/graphics-drivers/nvidia.md) + - [NVIDIA + Optimus](./config/graphical-session/graphics-drivers/optimus.md) + - [Xorg](./config/graphical-session/xorg.md) + - [Wayland](./config/graphical-session/wayland.md) + - [Fonts](./config/graphical-session/fonts.md) + - [Icons](./config/graphical-session/icons.md) + - [GNOME](./config/graphical-session/gnome.md) + - [KDE](./config/graphical-session/kde.md) + - [Multimedia](./config/media/index.md) + - [ALSA](./config/media/alsa.md) + - [PipeWire](./config/media/pipewire.md) + - [PulseAudio](./config/media/pulseaudio.md) + - [sndio](./config/media/sndio.md) + - [Bluetooth](./config/bluetooth.md) + - [TeX Live](./config/texlive.md) + - [External Applications](./config/external-applications.md) + - [Printing](./config/print/index.md) + - [Containers and Virtual Machines](./config/containers-and-vms/index.md) + - [Chroots and Containers](./config/containers-and-vms/chroot.md) + - [libvirt](./config/containers-and-vms/libvirt.md) + - [LXC](./config/containers-and-vms/lxc.md) + - [OpenPGP](./config/openpgp.md) + - [PHP](./config/php.md) +- [XBPS Package Manager](./xbps/index.md) + - [Advanced Usage](./xbps/advanced-usage.md) + - [Repositories](./xbps/repositories/index.md) + - [Mirrors](./xbps/repositories/mirrors/index.md) + - [Changing Mirrors](./xbps/repositories/mirrors/changing.md) + - [Using Tor Mirrors](./xbps/repositories/mirrors/tor.md) + - [Restricted Packages](./xbps/repositories/restricted.md) + - [Custom Repositories](./xbps/repositories/custom.md) + - [Signing Repositories](./xbps/repositories/signing.md) + - [Troubleshooting XBPS](./xbps/troubleshooting/index.md) + - [Common Issues](./xbps/troubleshooting/common-issues.md) + - [Static XBPS](./xbps/troubleshooting/static.md) +- [Contributing](./contributing/index.md) + - [Contributing To evolution-docs](./contributing/evolution-docs/index.md) diff --git a/src/about/about-this-handbook.md b/src/about/about-this-handbook.md new file mode 100644 index 0000000..97c3428 --- /dev/null +++ b/src/about/about-this-handbook.md @@ -0,0 +1,49 @@ +# About This Handbook + +This handbook is not an extensive guide on how to use and configure common Linux +software. The purpose of this document is to explain how to install, configure, +and maintain EvolutionOS systems, and to highlight the differences between common +Linux distributions and EvolutionOS. + +To search for a particular term within the Handbook, select the 'magnifying +glass' icon, or press 's'. + +Those looking for tips and tricks on how to configure a Linux system in general +should consult upstream software documentation. Additionally, the [Arch +Wiki](https://wiki.archlinux.org/) provides a fairly comprehensive outline of +common Linux software configuration, and a variety of internet search engines +are available for further assistance. + +## Reading The Manuals + +While this handbook does not provide a large amount of copy and paste +configuration instructions, it does provide links to the [man +pages](https://man.voidlinux.org/) for the referenced software wherever +possible. + +To learn how to use the [man(1)](https://man.voidlinux.org/man.1) man page +viewer, run the command `man man`. It can be configured by editing +`/etc/man.conf`; read [man.conf(5)](https://man.voidlinux.org/man.conf.5) for +details. + +EvolutionOS commonly uses the [mandoc](https://mandoc.bsd.lv/) toolset for man pages. mandoc was +formerly known as "mdocml", and is provided by the `mdocml` package. + +## Example Commands + +Examples in this guide may have snippets of commands to be run in your shell. +When you see these, any line beginning with `$` is run as your normal user. +Lines beginning with `#` are run as `root`. After either of these lines, there +may be example output from the command. + +### Placeholders + +Some examples include text with placeholders. Placeholders indicate where you +should substitute the appropriate information. For example: + +``` +# ln -s /etc/sv/ /var/service/ +``` + +This means you need to substitute the text `` with the actual +service name. diff --git a/src/about/history.md b/src/about/history.md new file mode 100644 index 0000000..3598ad2 --- /dev/null +++ b/src/about/history.md @@ -0,0 +1,20 @@ +# History + +Knowledge of the ancients, grepped from the Git logs themselves: + +- 2008-09-26: first Git import of + [void-packages](https://github.com/void-linux/void-packages) +- 2009-08-17: first Git import of [xbps](https://github.com/void-linux/xbps) +- 2011-06-25: first systemd commit in void-packages +- 2013-03-01: first [musl](https://musl.libc.org/) toolchains added +- 2014-07-14: begin switching to [LibreSSL](https://www.libressl.org/) +- 2014-07-28: switch from systemd to [runit](http://smarden.org/runit/) +- 2015-07-09: full aarch64 support with `linux4.1` +- 2018-07-06: first use of [Terraform for GitHub + permissions](https://github.com/void-linux/void-infrastructure/tree/master/terraform), + for increased transparency +- 2021-03-05: begin + [switching](https://github.com/void-linux/void-packages/commit/d90dba0ae27c4bb22cbb1722f70e4ed6d599e473) + to [OpenSSL](https://www.openssl.org/) +- 2023-07-Idk: forked void-packages to evolution-packages +- 2023-07-Stillidk: created evolution-linux website diff --git a/src/about/index.md b/src/about/index.md new file mode 100644 index 0000000..4ac32e3 --- /dev/null +++ b/src/about/index.md @@ -0,0 +1,31 @@ +# About + +Welcome to the EvolutionOS Handbook! Please be sure to read the "[About This +Handbook](./about-this-handbook.md)" section to learn how to use this +documentation effectively. A local copy of this handbook, in several formats, +can be [installed](../xbps/index.md) via the `evolution-docs` package and accessed +with the [evolution-docs(1)](https://hectabit.org/evolutionos/wiki) utility. + +EvolutionOS is an [rolling +release](https://en.wikipedia.org/wiki/Rolling_release) Linux distribution, with a focus on stability over +[bleeding-edge](https://en.wikipedia.org/wiki/Bleeding_edge_technology). In +addition, there are several features that make EvolutionOS unique: + +- The use of BusyBox over Coreutils, increasing speed and minimalism to an extream + +- The [musl libc](https://musl.libc.org/), which focuses on standards compliance + and correctness, has first class support. This allows us to build certain + components for musl systems statically, which would not be practical on glibc + systems. +- [runit](../config/services/index.md) is used for + [init(8)](https://man.voidlinux.org/init.8) and service supervision. This + allows EvolutionOS to support musl as a second libc choice, which would not be + possible with [systemd](https://www.freedesktop.org/wiki/Software/systemd/). + A side effect of this decision is a core system with clean and efficient + operation, and a small code base. +- The use of the booster initramfs over dracut, speeding up system startup and + reducing image sizes + +EvolutionOS is developed in the spare time of Tracker-Friendly, and is generally +considered stable enough for daily use. I do this for fun and hope that my +work will be useful to others. diff --git a/src/about/infradocs.md b/src/about/infradocs.md new file mode 100644 index 0000000..8fa3b8b --- /dev/null +++ b/src/about/infradocs.md @@ -0,0 +1,6 @@ +# InfraDocs + +[InfraDocs](https://infradocs.voidlinux.org/) is the meta-manual for the Void +project systems management. + +EvolutionOS doesn't make much use of this system. diff --git a/src/config/bluetooth.md b/src/config/bluetooth.md new file mode 100644 index 0000000..6478fea --- /dev/null +++ b/src/config/bluetooth.md @@ -0,0 +1,39 @@ +# Bluetooth + +Ensure the Bluetooth controller is not blocked. Use `rfkill` to check whether +there are any blocks and to remove soft blocks. If there is a hard block, there +is likely either a physical hardware switch or an option in the BIOS to enable +the Bluetooth controller. + +``` +$ rfkill +ID TYPE DEVICE SOFT HARD +0 wlan phy0 unblocked unblocked +1 bluetooth hci0 blocked unblocked + +# rfkill unblock bluetooth +``` + +## Installation + +Install the `bluez` package and enable the `bluetoothd` and `dbus` services. +Then, add your user to the `bluetooth` group and restart the `dbus` service, or +simply reboot the system. Note that restarting the `dbus` service may kill +processes making use of it. + +To use an audio device such as a wireless speaker or headset, ALSA users need to +install the `bluez-alsa` package. [PulseAudio](./media/pulseaudio.md) users do +not need any additional software. [PipeWire](./media/pipewire.md) users need +`libspa-bluetooth`. + +## Usage + +Manage Bluetooth connections and controllers using `bluetoothctl`, which +provides a command line interface and also accepts commands on standard input. + +Consult the [Arch Wiki](https://wiki.archlinux.org/index.php/Bluetooth#Pairing) +for an example of how to pair a device. + +## Configuration + +The main configuration file is `/etc/bluetooth/main.conf`. diff --git a/src/config/containers-and-vms/chroot.md b/src/config/containers-and-vms/chroot.md new file mode 100644 index 0000000..9e8de0d --- /dev/null +++ b/src/config/containers-and-vms/chroot.md @@ -0,0 +1,114 @@ +# Creating and using chroots and containers + +chroots and containers can be set up and used for many purposes, including: + +- running glibc software on musl (and vice versa) +- running software in a more controlled or sandboxed environment +- creating a rootfs for bootstrapping a system + +## Chroot Creation + +### xvoidstrap + +[`xvoidstrap(1)`](https://man.voidlinux.org/xvoidstrap.1) (from `xtools`) can be +used to create the chroot: + +``` +# mkdir +# XBPS_ARCH= xvoidstrap base-voidstrap +``` + +`` is only needed if you want to pre-install other packages in the +chroot. + +### Manual Creation + +Alternatively, this process can be done manually. + +Create a directory that will contain the chroot, then install a base system in +it via the `base-voidstrap` package: + +``` +# mkdir -p "/var/db/xbps/keys" +# cp -a /var/db/xbps/keys/* "/var/db/xbps/keys" +# XBPS_ARCH= xbps-install -S -r -R base-voidstrap +``` + +The `` may [vary depending on +architecture](../../xbps/repositories/index.md#the-main-repository). + +`` is only needed if you want to pre-install other packages in the +chroot. + +## Chroot Usage + +### xchroot + +[`xchroot(1)`](https://man.voidlinux.org/xchroot.1) (from `xtools`) can be used +to automatically set up and enter the chroot. + +### Manual Method + +Alternatively, this process can be done manually. + +If network access is required, copy `/etc/resolv.conf` into the chroot; +`/etc/hosts` may need to be copied as well. + +Several directories then need to be mounted as follows: + +``` +# mount -t proc none /proc +# mount -t sysfs none /sys +# mount --rbind /dev /dev +# mount --rbind /run /run +``` + +Use [chroot(1)](https://man.voidlinux.org/chroot.1) to change to the new root, +then run programs and do tasks as usual. Once finished with the chroot, unmount +the chroot using [umount(8)](https://man.voidlinux.org/umount.8). If any +destructive actions are taken on the chroot directory without unmounting first, +you may need to reboot to repopulate the affected directories. + +### Alternatives + +#### Bubblewrap + +[bwrap(1)](https://man.voidlinux.org/bwrap.1) (from the `bubblewrap` package) +has additional features like the ability for sandboxing and does not require +root access. + +`bwrap` is very flexible and can be used in many ways, for example: + +``` +$ bwrap --bind / \ + --dev /dev \ + --proc /proc \ + --bind /sys /sys \ + --bind /run /run \ + --ro-bind /etc/resolv.conf /etc/resolv.conf \ + --ro-bind /etc/passwd /etc/passwd \ + --ro-bind /etc/group /etc/group \ + +``` + +In this example, you will not be able to add or edit users or groups. When +running graphical applications with Xorg, you may need to also bind-mount +`~/.Xauthority` or other files or directories. + +The [bwrap(1) manpage](https://man.voidlinux.org/bwrap.1) and the [Arch Wiki +article](https://wiki.archlinux.org/title/Bubblewrap#Usage_examples) contain +more examples of `bwrap` usage. + +#### Flatpak + +[Flatpak](../external-applications.md#flatpak) is a convenient option for +running many applications, including graphical or proprietary ones, on both +glibc and musl systems. + +#### Application Containers + +If a more integrated and polished solution is desired, EvolutionOS also [provides OCI +containers](https://github.com/void-linux/void-docker/pkgs/container/void-linux) +that work with tools like [docker](https://www.docker.com) and +[podman](https://man.voidlinux.org/podman.1). These containers do not require +the creation of a chroot directory before usage. diff --git a/src/config/containers-and-vms/index.md b/src/config/containers-and-vms/index.md new file mode 100644 index 0000000..1a1fb65 --- /dev/null +++ b/src/config/containers-and-vms/index.md @@ -0,0 +1,10 @@ +# Containers and Virtual Machines + +This section describes how to set up some of the container and virtual machine +software available on EvolutionOS. + +## Section Contents + +- [Chroots and Containers](./chroot.md) +- [libvirt](./libvirt.md) +- [LXC](./lxc.md) diff --git a/src/config/containers-and-vms/libvirt.md b/src/config/containers-and-vms/libvirt.md new file mode 100644 index 0000000..14e8c29 --- /dev/null +++ b/src/config/containers-and-vms/libvirt.md @@ -0,0 +1,33 @@ +# libvirt + +[libvirt](https://libvirt.org/) is an API and daemon for managing platform +virtualization, supporting virtualization technologies such as LXC, KVM, QEMU, +Bhyve, Xen, VMWare, and Hyper-V. + +To use libvirt, install the `libvirt` package, ensure the `dbus` package is +installed, and [enable](../services/index.md#enabling-services) the `dbus`, +`libvirtd`, `virtlockd` and `virtlogd` services. The `libvirtd` daemon can be +reconfigured at runtime via +[virt-admin(1)](https://man.voidlinux.org/virt-admin.1). + +The `libvirt` package provides the [virsh(1)](https://man.voidlinux.org/virsh.1) +interface to libvirtd. `virsh` is an interactive shell and batch-scriptable tool +for performing management tasks, including creating, configuring and running +virtual machines, and managing networks and storage. Note that `virsh` usually +needs to be run as root, as described in the `virsh` man page: + +> Most virsh commands require root privileges to run due to the communications +> channels used to talk to the hypervisor. Running as non root will return an +> error. + +However, if you have the `polkit` and `dbus` packages installed and you enable +the `dbus` service, `libvirtd` will grant necessary privileges to any user added +to the `libvirt` group. + +An alternative to `virsh` is provided by the `virt-manager` and +`virt-manager-tools` packages. + +For general information on libvirt, refer to [the libvirt +wiki](https://wiki.libvirt.org/page/Main_Page) and [the wiki's +FAQ](https://wiki.libvirt.org/page/FAQ). For an introduction to libvirt usage, +refer to [the "VM lifecycle" page](https://wiki.libvirt.org/page/VM_lifecycle). diff --git a/src/config/containers-and-vms/lxc.md b/src/config/containers-and-vms/lxc.md new file mode 100644 index 0000000..e034dc3 --- /dev/null +++ b/src/config/containers-and-vms/lxc.md @@ -0,0 +1,128 @@ +# LXC + +The [Linux Containers project](https://linuxcontainers.org/) includes three +subprojects: [LXC](https://linuxcontainers.org/lxc/introduction/), +[LXD](https://linuxcontainers.org/lxd/introduction/) and +[LXCFS](https://linuxcontainers.org/lxcfs/introduction/). The project also +included the CGManager project, which has been deprecated in favor of the CGroup +namespace in recent kernels. + +## Configuring LXC + +Install the `lxc` package. + +Creating and running privileged containers as `root` does not require any +configuration; simply use the various `lxc-*` commands, such as +[lxc-create(1)](https://man.voidlinux.org/lxc-create.1), +[lxc-start(1)](https://man.voidlinux.org/lxc-start.1), +[lxc-attach(1)](https://man.voidlinux.org/lxc-attach.1), etc. + +### Creating unprivileged containers + +User IDs (UIDs) and group IDs (GIDs) normally range from 0 to 65535. +Unprivileged containers enhance security by mapping UID and GID ranges inside +each container to ranges not in use by the host system. The unused host ranges +must be *subordinated* to the user who will be running the unprivileged +containers. + +Subordinate UIDs and GIDs are assigned in the +[subuid(5)](https://man.voidlinux.org/subuid.5) and +[subgid(5)](https://man.voidlinux.org/subgid.5) files, respectively. + +To create unprivileged containers, first edit `/etc/subuid` and `/etc/subgid` to +delegate ranges. For example: + +``` +root:1000000:65536 +user:2000000:65536 +``` + +In each colon-delimited entry: + +- the first field is the user to which a subordinate range will be assigned; +- the second field is the smallest numeric ID defining a subordinate range; and +- the third field is the number of consecutive IDs in the range. + +The [usermod(8)](https://man.voidlinux.org/usermod.8) program may also be used +to manipulate suborinated IDs. + +Generally, the number of consecutive IDs should be an integer multiple of 65536; +the starting value is not important, except to ensure that the various ranges +defined in the file do not overlap. In this example, `root` controls UIDs (or, +from `subgid`, GIDs) ranging from 1000000 to 1065535, inclusive; `user` controls +IDs ranging from 2000000 to 2065535. + +Before creating a container, the user owning the container will need an +[lxc.conf(5)](https://man.voidlinux.org/lxc.conf.5) file specifying the subuid +and subgid range to use. For root-owned containers, this file resides at +`/etc/lxc/default.conf`; for unprivileged users, the file resides at +`~/.config/lxc/default.conf`. Mappings are described in lines of the form + +``` +lxc.idmap = u 0 1000000 65536 +lxc.idmap = g 0 1000000 65536 +``` + +The isolated `u` character indicates a UID mapping, while the isolated `g` +indicates a GID mapping. The first numeric value should generally always be 0; +this indicates the start of the UID or GID range *as seen from within the +container*. The second numeric value is the start of the corresponding range *as +seen from outside the container*, and may be an arbitrary value within the range +delegated in `/etc/subuid` or `/etc/subgid`. The final value is the number of +consecutive IDs to map. + +Note that, although the external range start is arbitrary, care must be taken to +ensure that the end of the range implied by the start and number does not extend +beyond the range of IDs delegated to the user. + +If configuring a non-root user, edit `/etc/lxc/lxc-usernet` as root to specify a +network device quota. For example, to allow the user named `user` to create up +to 10 `veth` devices connected to the `lxcbr0` bridge: + +``` +user veth lxcbr0 10 +``` + +The user can now create and use unprivileged containers with the `lxc-*` +utilities. To create a simple EvolutionOS container named `mycontainer`, use a command +similar to: + +``` +lxc-create -n mycontainer -t download -- \ + --dist voidlinux --release current --arch amd64 +``` + +You may substitute another architecture for `amd64`, and you may specify a +`musl` image by adding `--variant musl` to the end of the command. See the [LXC +Image Server](http://images.linuxcontainers.org) for a list of available +containers. + +By default, configurations and mountpoints for system containers are stored in +`/var/lib/lxc`, while configurations for user containers and mountpoints are +stored in `~/.local/share/lxc`. Both of these values can be modified by setting +`lxc.lxcpath` in the +[lxc.system.conf(5)](https://man.voidlinux.org/lxc.system.conf.5) file. The +superuser may launch unprivileged containers in the system `lxc.lxcpath` defined +in `/etc/lxc/lxc.conf`; regular users may launch unprivileged containers in the +personal `lxc.lxcpath` defined in `~/.config/lxc/lxc.conf`. + +All containers will share the same subordinate UID and GID maps by default. This +is permissible, but it means that an attacker who gains elevated access within +one container, and can somehow break out of that container, will have similar +access to other containers. To isolate containers from each other, alter the +`lxc.idmap` ranges in `default.conf` to point to a unique range *before* you +create each container. Trying to fix permissions on a container created with the +wrong map is possible, but inconvenient. + +## LXD + +LXD provides an alternative interface to LXC's `lxc-*` utilities. However, it +does not require the configuration described in [the previous section](#lxc). + +Install the `lxd` package, and [enable](../services/index.md#enabling-services) +the `lxd` service. + +LXD users must belong to the `lxd` group. + +Use the `lxc` command to manage instances, as described +[here](https://linuxcontainers.org/lxd/getting-started-cli/#lxd-client). diff --git a/src/config/cron.md b/src/config/cron.md new file mode 100644 index 0000000..fab29f0 --- /dev/null +++ b/src/config/cron.md @@ -0,0 +1,25 @@ +# Cron + +[cron](https://en.wikipedia.org/wiki/Cron) is a daemon for running programs at +regular intervals. The programs and intervals are specified in a `crontab` file, +which can be edited with [crontab(1)](https://man.voidlinux.org/crontab.1). +Running `crontab -e` as the superuser will edit the system crontab; otherwise, +it will edit the crontab for the current user. + +By default, a cron daemon is not installed. However, multiple cron +implementations are available, including +[cronie](https://github.com/cronie-crond/cronie/), +[dcron](http://www.jimpryor.net/linux/dcron.html), +[fcron](http://fcron.free.fr/) and more. + +Once you have chosen and installed an implementation, +[enable](./services/index.md#enabling-services) the corresponding service. There +is also a generic `crond` service which is maintained by the alternatives +system, but there is no real benefit in using it and just makes your setup +harder to follow. + +As an alternative to the standard cron implementations, you can use +[snooze(1)](https://man.voidlinux.org/snooze.1) together with the +`snooze-hourly`, `snooze-daily`, `snooze-weekly` and `snooze-monthly` services, +which are provided by the `snooze` package for this purpose. Each of these +services execute scripts in the respective `/etc/cron.*` directories. diff --git a/src/config/date-time.md b/src/config/date-time.md new file mode 100644 index 0000000..0429e2b --- /dev/null +++ b/src/config/date-time.md @@ -0,0 +1,83 @@ +# Date and Time + +To view your system's current date and time information, as well as make direct +changes to it, use [date(1)](https://man.voidlinux.org/date.1). + +## Timezone + +The default system timezone can be set by linking the timezone file to +`/etc/localtime`: + +``` +# ln -sf /usr/share/zoneinfo/ /etc/localtime +``` + +> Note: If the variable `TIMEZONE` is set in `/etc/rc.conf`, it should be +> removed or commented out, as this will override what has been set with `ln` on +> reboot. + +To change the timezone on a per user basis, the `TZ` variable can be exported +from your shell's profile: + +``` +export TZ= +``` + +Note that setting the *timezone* does not set the *time* (or date); instead, it +simply specifies an offset from +[UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time), as described in +[timezone(3)](https://man.voidlinux.org/timezone.3). + +## Hardware clock + +By default, the hardware clock in EvolutionOS is stored as UTC. Windows does not use +UTC by default, and if you are dual-booting, this will conflict with EvolutionOS. You +can either change Windows to use UTC, or change EvolutionOS Linux to use `localtime` by +setting the `HARDWARECLOCK` variable in `/etc/rc.conf`: + +``` +export HARDWARECLOCK=localtime +``` + +For more details, see [hwclock(8)](https://man.voidlinux.org/hwclock.8). + +## NTP + +To maintain accuracy of your system's clock, you can use the [Network Time +Protocol](https://en.wikipedia.org/wiki/Network_Time_Protocol) (NTP). + +EvolutionOS provides packages for three NTP daemons: NTP, OpenNTPD and Chrony. + +Once you have installed an NTP daemon, you can [enable the +service](../config/services/index.md#managing-services) for it, either through +its own service or the `ntpd` service managed by +[xbps-alternatives(1)](https://man.voidlinux.org/xbps-alternatives.1). + +### NTP + +NTP is the official reference implementation of the Network Time Protocol. + +The `ntp` package provides NTP and the `isc-ntpd` service. + +For further information, visit [the NTP site](https://www.ntp.org/). + +### OpenNTPD + +OpenNTPD focuses on providing a secure, lean NTP implementation which "just +works" with reasonable accuracy for a majority of use-cases. + +The `openntpd` package provides OpenNTPD and the `openntpd` service. + +For further information, visit [the OpenNTPD site](https://www.openntpd.org/). + +### Chrony + +Chrony is designed to work well in a variety of conditions; it can synchronize +faster and with greater accuracy than NTP. + +The `chrony` package provides Chrony and the `chronyd` service. + +The Chrony site provides [a brief overview of its advantages over +NTP](https://chrony.tuxfamily.org/faq.html#_how_does_chrony_compare_to_ntpd), as +well as [a detailed feature comparison between Chrony, NTP and +OpenNTPD](https://chrony.tuxfamily.org/comparison.html). diff --git a/src/config/external-applications.md b/src/config/external-applications.md new file mode 100644 index 0000000..e760a6a --- /dev/null +++ b/src/config/external-applications.md @@ -0,0 +1,102 @@ +# External Applications + +## Programming Languages + +The EvolutionOS repositories have a number of Python and Lua packages. If possible, +install packages from the EvolutionOS repositories or consider packaging the library or +application you need. Packaging your application allows for easier system +maintenance and can benefit other EvolutionOS users, so consider making a pull +request for it. The contribution instructions can be found +[here](https://github.com/evolution-linux/evolution-packages/blob/master/CONTRIBUTING.md). + +To keep packages smaller, EvolutionOS has separate `devel` packages for header files +and development tools. If you install a library or application via a language's +package manager (e.g. `pip`, `gem`), or compile one from source, you may need to +install the programming language's `-devel` package. This is specially relevant +for `musl` libc users, due to pre-built binaries usually targeting `glibc` +instead. + +| Language | Package Manager | Evolution Package | +|----------|--------------------------------|-----------------| +| Python3 | pip, anaconda, virtualenv, etc | `python3-devel` | +| Python2 | pip, anaconda, virtualenv, etc | `python2-devel` | +| Ruby | gem | `ruby-devel` | +| lua | luarocks | `lua-devel` | + +## Restricted Packages + +Some packages have legal restrictions on their distribution (e.g. Discord), may +be too large, or have another condition that makes it difficult for EvolutionOS to +distribute. These packages have build templates, but the packages themselves are +not built or distributed. As such, they must be built locally. For more +information see the page on [restricted +packages](../xbps/repositories/restricted.md). + +## Non-x86_64 Arch + +The EvolutionOS build system runs on x86_64 servers, both for compiling and cross +compiling packages. However, some packages (e.g. `libreoffice`) do not support +cross-compilation. These packages have to be built locally on a computer running +the same architecture and libc as the system on which the package is to be used. +To learn how to build packages, refer to [the README for the evolution-packages +repository](https://github.com/evolution-linux/evolution-packages/blob/master/README.md). + +## Flatpak + +Flatpak is another method for installing external proprietary applications on +Linux. For information on using Flatpak with EvolutionOS, see the [official +Flatpak documentation](https://flatpak.org/setup/Void%20Linux/). + +If sound is not working for programs installed using Flatpak, +[PulseAudio](./media/pulseaudio.md) auto-activation might not be working +correctly. Make sure PulseAudio is running before launching the program. + +Note that Flatpak's sandboxing will not necessarily protect you from any +security and/or privacy-violating features of proprietary software. + +### Troubleshooting + +Some apps may not function properly (e.g. not being able to access the host +system's files). Some of these issues can be fixed by installing one or more of +the `xdg-desktop-portal`, `xdg-desktop-portal-gtk`, `xdg-user-dirs`, +`xdg-user-dirs-gtk` or `xdg-utils` packages. + +Some Flatpaks require [D-Bus](./session-management.md#d-bus) and/or +[Pulseaudio](./media/pulseaudio.md). + +## AppImages + +An [AppImage](https://appimage.org/) is a file that bundles an application with +everything needed to run it. An AppImage can be used by making it executable and +running it; installation is not required. AppImages can be run in a sandbox, +such as [firejail](https://firejail.wordpress.com/). + +Some of the applications for which an AppImage is available can be found on +[AppImageHub](https://appimage.github.io/). + +AppImages do not yet work on musl installations. + +## Octave Packages + +Some Octave packages require external dependencies to compile and run. For +example, to build the control package, you must install the `openblas-devel`, +`libgomp-devel`, `libgfortran-devel`, `gcc-fortran`, and `gcc` packages. + +## MATLAB + +To use MATLAB's help browser, live scripts, add-on installer, and simulink, +install the `libselinux` package. + +## Steam + +Steam can be installed either via a native package, which requires [enabling the +"nonfree" repository](../xbps/repositories/index.md#nonfree), or via +[Flatpak](#flatpak). The list of dependencies for different platforms and +troubleshooting information for the native package can be found in its +[Evolution-specific documentation](./package-documentation/index.html), while this +section deals with potential issues faced by Flatpak users. + +If you are using a different drive to store your game library, the +`--filesystem` option from +[flatpak-override(1)](https://man.voidlinux.org/flatpak-override.1) can prove +useful. diff --git a/src/config/firmware.md b/src/config/firmware.md new file mode 100644 index 0000000..3b2acd0 --- /dev/null +++ b/src/config/firmware.md @@ -0,0 +1,39 @@ +# Firmware + +EvolutionOS provides a number of firmware packages in the repositories. Some firmware +is only available if you have enabled the +[nonfree](../xbps/repositories/index.md#nonfree) repository. + +## Microcode + +Microcode is loaded onto the CPU or GPU at boot by the BIOS, but can be replaced +later by the OS itself. An update to microcode can allow a CPU's or GPU's +behavior to be modified to work around certain yet to be discovered bugs, +without the need to replace the hardware. + +### Intel + +Install the Intel microcode package, `intel-ucode`. This package is in the +nonfree repo, which has to be [enabled](../xbps/repositories/index.md#nonfree). +After installing this package, it is necessary to regenerate your +[initramfs](./kernel.md#kernel-hooks). For subsequent updates, the microcode +will be added to the initramfs automatically. + +### AMD + +Install the AMD package, `linux-firmware-amd`, which contains microcode for both +AMD CPUs and GPUs. AMD CPUs and GPUs will automatically load the microcode, no +further configuration required. + +### Verification + +The `/proc/cpuinfo` file has some information under `microcode` that can be used +to verify the microcode update. + +## Removing firmware + +By default, `linuxX.Y` packages and the `base-system` package install a number +of firmware packages. It is not necessary to remove unused firmware packages, +but if you wish to do so, you can configure XBPS to +[ignore](../xbps/advanced-usage.md#ignoring-packages) those packages, then +remove them. diff --git a/src/config/graphical-session/fonts.md b/src/config/graphical-session/fonts.md new file mode 100644 index 0000000..7beba71 --- /dev/null +++ b/src/config/graphical-session/fonts.md @@ -0,0 +1,17 @@ +# Fonts + +To customize font display in your graphical session, you can use configurations +provided in `/usr/share/fontconfig/conf.avail/`. To do so, create a symlink to +the relevant `.conf` file in `/etc/fonts/conf.d/`, then use +[xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) to +reconfigure the `fontconfig` package. + +For example, to disable use of bitmap fonts: + +``` +# ln -s /usr/share/fontconfig/conf.avail/70-no-bitmaps.conf /etc/fonts/conf.d/ +# xbps-reconfigure -f fontconfig +``` + +Use [fc-conflist(1)](https://man.voidlinux.org/fc-conflist.1) to list which +configurations are in effect. diff --git a/src/config/graphical-session/gnome.md b/src/config/graphical-session/gnome.md new file mode 100644 index 0000000..a2efb9d --- /dev/null +++ b/src/config/graphical-session/gnome.md @@ -0,0 +1,29 @@ +# GNOME + +## Pre-installation + +GNOME supports both X and Wayland sessions. Follow the "[Wayland](./wayland.md)" +or "[Xorg](./xorg.md)" sections to setup your preferred environment. + +Install the `dbus` package, ensure the `dbus` service is enabled, and reboot for +the changes to take effect. + +## Installation + +Install the `gnome` package for a GNOME environment which includes the base +GNOME desktop and a subset of GNOME applications. Additional applications are +available via the `gnome-apps` package. + +A minimal GNOME environment can be created by installing the `gnome-core` +package. Note, however, that not all GNOME features may be present or +functional. + +If you require [ZeroConf](http://www.zeroconf.org/) support, install the `avahi` +package and enable the `avahi-daemon` service. + +## Starting GNOME + +The `gdm` package provides the `gdm` service for the GNOME Display Manager; +[test the service](../services/index.md#testing-services) before enabling it. +GDM defaults to providing a Wayland session via the `mutter` window manager, but +an X session can be chosen instead. diff --git a/src/config/graphical-session/graphics-drivers/amd.md b/src/config/graphical-session/graphics-drivers/amd.md new file mode 100644 index 0000000..da2e6c8 --- /dev/null +++ b/src/config/graphical-session/graphics-drivers/amd.md @@ -0,0 +1,30 @@ +# AMD or ATI + +AMD GPU support requires the `linux-firmware-amd` package. If you have installed +the `linux` or `linux-lts` packages, it will be installed as a dependency. If +you installed a version-specific kernel package (e.g., `linux5.4`), it may be +necessary to manually install `linux-firmware-amd`. + +## OpenGL + +Install the Mesa DRI package, `mesa-dri`. This is already included in the `xorg` +meta-package, but it is needed when installing Xorg via `xorg-minimal` or for +running a Wayland compositor. + +## Vulkan + +Install `vulkan-loader`, the Khronos Vulkan Loader. Then install one or both of +the Mesa AMD Vulkan driver, `mesa-vulkan-radeon`; or the GPUOpen AMD Vulkan +driver, `amdvlk`. + +## Xorg + +Installing the `xorg` meta-package will pull in both `xf86-video-amdgpu` and, +for older hardware, `xf86-video-ati`. If you install `xorg-minimal`, choose one +of these Xorg driver packages to match your hardware. The `amdgpu` driver should +support cards built on AMD's "Graphics Core Next 1.2" architecture, introduced +circa 2012. + +## Video acceleration + +Install the `mesa-vaapi` and `mesa-vdpau` packages. diff --git a/src/config/graphical-session/graphics-drivers/index.md b/src/config/graphical-session/graphics-drivers/index.md new file mode 100644 index 0000000..6b53cfe --- /dev/null +++ b/src/config/graphical-session/graphics-drivers/index.md @@ -0,0 +1,11 @@ +# Graphics Drivers + +This section covers basic graphics setup depending on the hardware configuration +of your system. + +## Section Contents + +- [AMD or ATI](./amd.md) +- [Intel](./intel.md) +- [NVIDIA](./nvidia.md) +- [NVIDIA Optimus](./optimus.md) diff --git a/src/config/graphical-session/graphics-drivers/intel.md b/src/config/graphical-session/graphics-drivers/intel.md new file mode 100644 index 0000000..1b0920b --- /dev/null +++ b/src/config/graphical-session/graphics-drivers/intel.md @@ -0,0 +1,48 @@ +# Intel + +Intel GPU support requires the `linux-firmware-intel` package. If you have +installed the `linux` or `linux-lts` packages, it will be installed as a +dependency. If you installed a version-specific kernel package (e.g., +`linux5.4`), it may be necessary to manually install `linux-firmware-intel`. + +## OpenGL + +OpenGL requires the Mesa DRI package, `mesa-dri`. This is provided by the `xorg` +meta-package, but will need to be installed manually when using the +`xorg-minimal` package or running a Wayland compositor. + +## Vulkan + +Install the Khronos Vulkan Loader and the Mesa Intel Vulkan driver packages, +respectively `vulkan-loader` and `mesa-vulkan-intel`. + +## Video acceleration + +Install the `intel-video-accel` meta-package: + +This will install all the Intel VA-API drivers. `intel-media-driver` will be +used by default, but this choice can be overridden at runtime via the +environment variable `LIBVA_DRIVER_NAME`: + +| Driver Package | Supported GPU Gen | Explicit selection | +|----------------------|-------------------|--------------------------| +| `libva-intel-driver` | up to Coffee Lake | `LIBVA_DRIVER_NAME=i965` | +| `intel-media-driver` | from Broadwell | `LIBVA_DRIVER_NAME=iHD` | + +## Troubleshooting + +The kernels packaged by EvolutionOS are configured with +`CONFIG_INTEL_IOMMU_DEFAULT_ON=y`, which can lead to issues with their graphics +drivers, as reported by the [kernel +documentation](https://www.kernel.org/doc/html/latest/x86/iommu.html#graphics-problems). +To fix this, it is necessary to disable IOMMU for the integrated GPU. This can +be done by adding `intel_iommu=igfx_off` to your [kernel +cmdline](../../kernel.md#cmdline). This problem is expected to happen on the +Broadwell generation of internal GPUs. If you have another internal GPU and your +issues are fixed by this kernel option, you should file a bug reporting the +problem to kernel developers. + +For newer Intel chipsets, the [DDX](../xorg.md#ddx) drivers may interfere with +correct operation. This is characterized by graphical acceleration not working +and general graphical instability. If this is the case, try removing all +`xf86-video-*` packages. diff --git a/src/config/graphical-session/graphics-drivers/nvidia.md b/src/config/graphical-session/graphics-drivers/nvidia.md new file mode 100644 index 0000000..a75f03d --- /dev/null +++ b/src/config/graphical-session/graphics-drivers/nvidia.md @@ -0,0 +1,96 @@ +# NVIDIA + +## nouveau (Open Source Driver) + +This is a reverse engineered driver largely developed by the community, with +some documentation provided by Nvidia. It tends to perform well on older +hardware, and is required to use a large portion of the available Wayland +compositors. + +At the time of writing, graphics cards starting with second generation Maxwell +(GTX 9xx) are unable to perform at their full potential with `nouveau`. This is +because the `linux-firmware` collection is missing signed firmware blobs needed +to reclock these cards past their boot frequencies. + +To use `nouveau` with Wayland, you only need the `mesa-dri` package, which +provides the accelerated OpenGL driver. On X11, you also need an appropriate +Xorg driver. You can either install `xf86-video-nouveau` or use the universal +`modesetting` driver bundled with Xorg (this is the only option on Tegra based +ARM boards). The former can make use of GPU-specific 2D acceleration paths, +which is primarily useful on older cards with specialized fixed function +hardware (the `modesetting` driver will accelerate 2D using OpenGL via GLAMOR). +When in doubt, it's a good idea to try `xf86-video-nouveau` first. + +Note: `xf86-video-nouveau` is usually installed by default if you use the `xorg` +metapackage. If you use `xorg-minimal`, you will need to install it manually, +either directly or through `xorg-video-drivers`. + +## nvidia (Proprietary Driver) + +The proprietary drivers are available in the [nonfree +repository](../../../xbps/repositories/index.md#nonfree). + +Check if your graphics card belongs to the [legacy +branch](https://www.nvidia.com/en-us/drivers/unix/legacy-gpu/). If it does not, +install the `nvidia` package. Otherwise you should install the appropriate +legacy driver, `nvidia470` or `nvidia390`. The older legacy driver, `nvidia340`, +is no longer available, and users are encouraged to [switch to +nouveau](#reverting-from-nvidia-to-nouveau). + +| Brand | Type | Model | Driver Package | +|--------|-------------|----------------|----------------| +| NVIDIA | Proprietary | 800+ | `nvidia` | +| NVIDIA | Proprietary | 600/700 | `nvidia470` | +| NVIDIA | Proprietary | 400/500 Series | `nvidia390` | + +The proprietary driver integrates in the kernel through +[DKMS](../../kernel.md#dynamic-kernel-module-support-dkms). + +This driver offers better performance and power handling, and is recommended +where performance is needed. + +## 32-bit program support (glibc only) + +In order to run 32-bit programs with driver support, you need to install +additional packages. + +If using the `nouveau` driver, install the `mesa-dri-32bit` package. + +If using the `nvidia` driver, install the `nvidia-libs-32bit` package. `` +represents the legacy driver version (`470` or `390`) or can be left empty for +the main driver. + +## Reverting from nvidia to nouveau + +### Uninstalling nvidia + +In order to revert to the `nouveau` driver, install the [`nouveau` +driver](#nouveau-open-source-driver) (if it was not installed already), then +remove the `nvidia`, `nvidia470`, or `nvidia390` package, as appropriate. + +If you were using the obsolete `nvidia340` driver, you might need to install the +`libglvnd` package after removing the `nvidia340` package. + +### Keeping both drivers + +It is possible to use the `nouveau` driver while still having the `nvidia` +driver installed. To do so, remove the blacklisting of `nouveau` in +`/etc/modprobe.d/nouveau_blacklist.conf`, `/usr/lib/modprobe.d/nvidia.conf`, or +`/usr/lib/modprobe.d/nvidia-dkms.conf` by commenting it out: + +``` +#blacklist nouveau +``` + +For Xorg, specify that it should load the `nouveau` driver rather than the +`nvidia` driver by creating the file `/etc/X11/xorg.conf.d/20-nouveau.conf` with +the following content: + +``` +Section "Device" + Identifier "Nvidia card" + Driver "nouveau" +EndSection +``` + +You may need to reboot your system for these changes to take effect. diff --git a/src/config/graphical-session/graphics-drivers/optimus.md b/src/config/graphical-session/graphics-drivers/optimus.md new file mode 100644 index 0000000..0ed52ad --- /dev/null +++ b/src/config/graphical-session/graphics-drivers/optimus.md @@ -0,0 +1,95 @@ +# NVIDIA Optimus + +NVIDIA Optimus refers to a dual graphics configuration found on laptops +consisting of an Intel integrated GPU and a discrete NVIDIA GPU. + +There are different methods to take advantage of the NVIDIA GPU, which depend on +the driver version supported by your hardware. + +In order to determine the correct driver to install, it is not enough to look at +the "Supported Products" list on NVIDIA's website, because they are not +guaranteed to work in an Optimus configuration. So the only way is to try +installing the latest `nvidia`, rebooting, and looking at the kernel log. If +your device is not supported, you will see a message like this: + +``` +NVRM: The NVIDIA GPU xxxx:xx:xx.x (PCI ID: xxxx:xxxx) +NVRM: installed in this system is not supported by the xxx.xx +NVRM: NVIDIA Linux driver release. Please see 'Appendix +NVRM: A - Supported NVIDIA GPU Products' in this release's +NVRM: README, available on the Linux driver download page +NVRM: at www.nvidia.com. +``` + +which means you have to uninstall `nvidia` and install the legacy `nvidia390`. + +A summary of the methods supported by EvolutionOS, which are mutually exclusive: + +[PRIME Render Offload](#prime-render-offload) + +- available on `nvidia` and `nvidia470` +- allows to switch to the NVIDIA GPU on a per-application basis +- more flexible but power saving capabilities depend on the hardware (pre-Turing + devices are not shut down completely) + +Offloading Graphics Display with RandR 1.4 + +- available on `nvidia`, `nvidia470`, and `nvidia390` +- allows to choose which GPU to use at the start of the X session +- less flexible, but allows the user to completely shut down the NVIDIA GPU when + not in use, thus saving power + +[Bumblebee](#bumblebee) + +- available on `nvidia`, `nvidia470`, and `nvidia390` +- allows to switch to the NVIDIA GPU on a per-application basis +- unofficial method, offers poor performance + +[Nouveau PRIME](#nouveau-prime) + +- uses the open source driver `nouveau` +- allows to switch to the NVIDIA GPU on a per-application basis +- `nouveau` is a reverse-engineered driver and offers poor performance + +You can check the currently used GPU by searching for `renderer string` in the +output of the `glxinfo` command. It is necessary to install the `glxinfo` +package for this. For the first two alternatives below, it is also possible to +verify that a process is using the NVIDIA GPU by checking the output of +`nvidia-smi`. + +## PRIME Render Offload + +In this method, GPU switching is done by setting environment variables when +executing the application to be rendered on the NVIDIA GPU. The wrapper script +`prime-run` is available from the `nvidia` package, and can be used as shown +below: + +``` +$ prime-run +``` + +For more information, see NVIDIA's +[README](https://download.nvidia.com/XFree86/Linux-x86_64/440.44/README/primerenderoffload.html) + +## Bumblebee + +Enable the `bumblebeed` service and add the user to the `bumblebee` group. This +requires a re-login to take effect. + +Run the application to be rendered on the NVIDIA GPU with `optirun`: + +``` +$ optirun +``` + +## Nouveau PRIME + +This method uses the open source `nouveau` driver. If the NVIDIA drivers are +installed, it is necessary to [configure the system to use +`nouveau`](./nvidia.md#reverting-from-nvidia-to-nouveau). + +Set `DRI_PRIME=1` to run an application on the NVIDIA GPU: + +``` +$ DRI_PRIME=1 +``` diff --git a/src/config/graphical-session/icons.md b/src/config/graphical-session/icons.md new file mode 100644 index 0000000..9184c48 --- /dev/null +++ b/src/config/graphical-session/icons.md @@ -0,0 +1,18 @@ +# Icons + +## GTK + +By default, GTK-based applications try to use the Adwaita icon theme for +application icons. Consequently, installation of the `gtk+3` package will also +install the `adwaita-icon-theme` package. If you wish to use a different theme, +install the relevant package, then specify the theme in +`/etc/gtk-3.0/settings.ini` or `~/.config/gtk-3.0/settings.ini`. +`adwaita-icon-theme` can be removed after +[ignoring](../../xbps/advanced-usage.md#ignoring-packages) the package. + +For information about how to specify a different GTK icon theme in +`settings.ini`, refer to [the GtkSettings +documentation](https://developer.gnome.org/gtk3/stable/GtkSettings.html#GtkSettings.properties), +in particular the +"[gtk-icon-theme-name](https://developer.gnome.org/gtk3/stable/GtkSettings.html#GtkSettings--gtk-icon-theme-name)" +property. diff --git a/src/config/graphical-session/index.md b/src/config/graphical-session/index.md new file mode 100644 index 0000000..4604bd5 --- /dev/null +++ b/src/config/graphical-session/index.md @@ -0,0 +1,11 @@ +# Graphical Session + +In order to configure a graphical session, you need: + +- [Graphics drivers](./graphics-drivers/index.md) +- A basis for your graphical session: [Xorg](./xorg.md) or + [Wayland](./wayland.md) + +You may also need: + +- [Session management tools](../session-management.md) diff --git a/src/config/graphical-session/kde.md b/src/config/graphical-session/kde.md new file mode 100644 index 0000000..ee0a980 --- /dev/null +++ b/src/config/graphical-session/kde.md @@ -0,0 +1,34 @@ +# KDE + +## Installation + +Install the `kde5` package, and optionally, the `kde5-baseapps` package. + +To use the "Networks" widget, enable the `dbus` and `NetworkManager` services. + +Installing the `kde5` package also installs the `sddm` package, which provides +the `sddm` service for the Simple Desktop Display Manager. This service depends +on the `dbus` service being enabled; [test the +service](../services/index.md#testing-services) before enabling it. If you are +not intending to run SDDM via a remote X server, you will need to install either +the `xorg-minimal` package or the `xorg` package. By default, SDDM will start an +X-based Plasma session, but you can request a Wayland-based Plasma session +instead. + +If you wish to start an X-based session from the console, use +[startx](./xorg.md#startx) to run `startplasma-x11`. For a Wayland-based +session, run `startplasma-wayland` directly. + +## Dolphin + +Dolphin is the default file manager of the KDE desktop environment. It can be +installed on its own by installing the `dolphin` package, or it can be installed +as part of the `kde5-baseapps` meta-package. + +### Thumbnail Previews + +To enable thumbnail file previews, install the `kdegraphics-thumbnailers` +package. If you want video thumbnails, the `ffmpegthumbs` package is also +necessary. Enable previews in "Control" -> "Configure Dolphin" -> "General" -> +"Previews" by checking the corresponding boxes. File previews will be shown for +the selected file types after clicking "Preview" in Dolphin's toolbar. diff --git a/src/config/graphical-session/wayland.md b/src/config/graphical-session/wayland.md new file mode 100644 index 0000000..bba39e4 --- /dev/null +++ b/src/config/graphical-session/wayland.md @@ -0,0 +1,94 @@ +# Wayland + +This section details the manual installation and configuration of Wayland +compositors and related services and utilities. + +## Installation + +Unlike [Xorg](./xorg.md), Wayland implementations combine the display server, +the window manager and the compositor in a single application. + +### Desktop Environments + +GNOME, KDE Plasma and Enlightenment have Wayland sessions. GNOME uses its +Wayland session by default. When using these desktop environments, applications +built with GTK+ will automatically choose the Wayland backend, while Qt5 and EFL +applications might require [setting some environment +variables](#native-applications) if used outside KDE or Enlightenment, +respectively. + +### Standalone compositors + +EvolutionOS currently packages the following Wayland compositors: + +- Weston: reference compositor for Wayland +- Sway: an i3-compatible Wayland compositor +- Wayfire: 3D Wayland compositor +- Hikari: a stacking compositor with some tiling features +- Cage: a Wayland kiosk +- River: a dynamic tiling Wayland compositor +- labwc: a window-stacking compositor, inspired by Openbox + +Note that evolution-desktop exists, which uses Wayfire and bundles gtkgreet and polkit for +ease of access. + +### Video drivers + +Both GNOME and KDE Plasma have EGLStreams backends for Wayland, which means they +can use the proprietary NVIDIA drivers. Most other Wayland compositors require +drivers that implement the GBM interface. The main driver for this purpose is +provided by the `mesa-dri` package. The "[Graphics +Drivers](./graphics-drivers/index.md)" section has more details regarding +setting up graphics in different systems. + +### Seat management + +Wayland compositors require some way of controlling the video display and +accessing input devices. In EvolutionOS systems, this requires a seat manager service, +which can be either elogind or seatd. Enabling them is explained in the +["Session and Seat Management"](../session-management.md) session. + +### Native applications + +[Qt5](https://wayland.freedesktop.org/qt5.html)-based applications require +installing the `qt5-wayland` package and setting the environment variable +`QT_QPA_PLATFORM=wayland-egl` to enable their Wayland backend. Some KDE specific +applications also require installing the `kwayland` package. +[EFL](https://wayland.freedesktop.org/efl.html)-based applications require +setting the environment variable `ELM_DISPLAY=wl`, and can have issues without +it, due to not supporting XWayland properly. [SDL](https://libsdl.org)-based +applications require setting the environment variable `SDL_VIDEODRIVER=wayland`. +[GTK+](https://wiki.gnome.org/Initiatives/Wayland/GTK%2B)-based applications +should use the Wayland backend automatically. Information about other toolkits +can be found in the [Wayland +documentation](https://wayland.freedesktop.org/toolkits.html). + +Media applications, such as [mpv(1)](https://man.voidlinux.org/mpv.1), +[vlc(1)](https://man.voidlinux.org/vlc.1) and `imv` work natively on Wayland. + +#### Web browsers + +Mozilla Firefox ships with a Wayland backend which is disabled by default. To +enable the Wayland backend, either set the environment variable +`MOZ_ENABLE_WAYLAND=1` before running `firefox` or use the provided +`firefox-wayland` script. + +Browsers based on GTK+ or Qt5, such as Midori and +[qutebrowser(1)](https://man.voidlinux.org/qutebrowser.1), should work on +Wayland natively. + +#### Running X applications inside Wayland + +If an application doesn't support Wayland, it can still be used in a Wayland +context. XWayland is an X server that bridges this gap for most Wayland +compositors, and is installed as a dependency for most of them. Its package is +`xorg-server-xwayland`. For Weston, the correct package is `weston-xwayland`. + +## Configuration + +The Wayland library requires the +[`XDG_RUNTIME_DIR`](../session-management.html#xdg_runtime_dir) environment +variable to determine the directory for the Wayland socket. + +It is also possible that some applications use the `XDG_SESSION_TYPE` +environment variable in some way, which requires that you set it to `wayland`. diff --git a/src/config/graphical-session/xorg.md b/src/config/graphical-session/xorg.md new file mode 100644 index 0000000..eeb75ce --- /dev/null +++ b/src/config/graphical-session/xorg.md @@ -0,0 +1,128 @@ +# Xorg + +This section details the manual installation and configuration of the Xorg +display server and common related services and utilities. If you would just like +to install a full desktop environment, it is recommended to try the [xfce +image](../../installation/live-images/index.md#xfce-image). + +## Installation + +EvolutionOS provides a comprehensive `xorg` package which installs the server and all +of the free video drivers, input drivers, fonts, and base applications. This +package is a safe option, and should be adequate for most systems which don't +require proprietary video drivers. + +If you would like to select only the packages you need, the `xorg-minimal` +package contains the base xorg server *only*. If you install only +`xorg-minimal`, you will likely need to install a font package (like +`xorg-fonts`), a terminal emulator (like `xterm`), and a window manager to have +a usable graphics system. + +## Video Drivers + +EvolutionOS provides both open-source and proprietary (non-free) video drivers. + +### Open Source Drivers + +Xorg can use two categories of open source drivers: DDX or modesetting. + +#### DDX + +The DDX drivers are installed with the `xorg` package by default, or may be +installed individually if the `xorg-minimal` package was installed. They are +provided by the `xf86-video-*` packages. + +For advanced configuration, see the man page corresponding to the vendor name, +like [intel(4)](https://man.voidlinux.org/intel.4). + +#### Modesetting + +Modesetting requires the `mesa-dri` package, and no additional vendor-specific +driver package. + +Xorg defaults to DDX drivers if they are present, so in this case modesetting +must be explicitly selected: see [Forcing the modesetting +driver](#forcing-the-modesetting-driver). + +For advanced configuration, see +[modesetting(4)](https://man.voidlinux.org/modesetting.4). + +### Proprietary Drivers + +EvolutionOS also provides [proprietary NVIDIA drivers](./graphics-drivers/nvidia.md), +which are available in the [nonfree +repository](../../xbps/repositories/index.md#nonfree). + +## Input Drivers + +A number of input drivers are available for Xorg. If `xorg-minimal` was +installed and a device is not responding, or behaving unexpectedly, a different +driver may correct the issue. These drivers can grab everything from power +buttons to mice and keyboards. They are provided by the `xf86-input-*` packages. + +## Xorg Configuration + +Although Xorg normally auto-detects drivers and configuration is not needed, a +config for a specific keyboard driver may look something like a file +`/etc/X11/xorg.conf.d/30-keyboard.conf` with the contents: + +``` +Section "InputClass" + Identifier "keyboard-all" + Driver "evdev" + MatchIsKeyboard "on" +EndSection +``` + +### Forcing the modesetting driver + +Create the file `/etc/X11/xorg.conf.d/10-modesetting.conf`: + +``` +Section "Device" + Identifier "GPU0" + Driver "modesetting" +EndSection +``` + +and restart Xorg. Verify that the configuration has been picked up with: + +``` +$ grep -m1 '(II) modeset([0-9]+):' /var/log/Xorg.0.log +``` + +If there is a match, modesetting is being used. + +## Starting X Sessions + +### startx + +The `xinit` package provides the [startx(1)](https://man.voidlinux.org/startx.1) +script as a frontend to [xinit(1)](https://man.voidlinux.org/xinit.1), which can +be used to start X sessions from the console. For example, to start +[i3(1)](https://man.voidlinux.org/i3.1), edit `~/.xinitrc` to contain `exec +/bin/i3` on the last line. + +To start arbitrary programs together with an X session, add them in `~/.xinitrc` +before the last line. For example, to start +[pipewire(1)](https://man.voidlinux.org/pipewire.1) before starting i3, add +`pipewire &` before the last line. + +A `~/.xinitrc` file which starts `pipewire` and `i3` is shown below: + +``` +pipewire & +exec /bin/i3 +``` + +Then call `startx` to start a session. + +If a D-Bus session bus is required, you can [manually start +one](../session-management.md#d-bus). + +### Display Managers + +Display managers (DMs) provide a graphical login UI. A number of DMs are +available in the EvolutionOS repositories, including `greetd / gtkgreet` (the recommended DM),`gdm` (the GNOME DM), `sddm` (the +KDE DM) and `lightdm`. When setting up a display manager, be sure to [test the +service](../services/index.md#testing-services) before enabling it. diff --git a/src/config/index.md b/src/config/index.md new file mode 100644 index 0000000..3f9f6ea --- /dev/null +++ b/src/config/index.md @@ -0,0 +1,4 @@ +# Configuration + +This section and its subsections provide information about configuring your EvolutionOS +system. diff --git a/src/config/kernel.md b/src/config/kernel.md new file mode 100644 index 0000000..ce815db --- /dev/null +++ b/src/config/kernel.md @@ -0,0 +1,250 @@ +# Kernel + +## Kernel series + +EvolutionOS provides many kernel series in the default repository. These are +named `linux.`: for example, `linux4.19`. You can query for all available +kernel series by running: + +``` +$ xbps-query --regex -Rs '^linux[0-9.]+-[0-9._]+' +``` + +The `linux` meta package, installed by default, depends on one of the kernel +packages, usually the package containing the latest mainline kernel that works +with all DKMS modules. Newer kernels might be available in the repository, but +are not necessarily considered stable enough to be the default; use these at +your own risk. If you wish to use a more recent kernel and have DKMS modules +that you need to build, install the relevant `linux.-headers` package, +then use [xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) to +reconfigure the `linux.` package you installed. This will build the DKMS +modules. + +## Removing old kernels + +When updating the kernel, old versions are left behind in case it is necessary +to roll back to an older version. Over time, old kernel versions can accumulate, +consuming disk space and increasing the time taken by DKMS module updates. +Furthermore, if `/boot` is a separate partition and fills up with old kernels, +updating can fail or result in incomplete initramfs filesystems to be generated +and result in kernel panics if they are being booted. Thus, it may be advisable +to clean old kernels from time to time. + +Removing old kernels is done using the +[vkpurge(8)](https://man.voidlinux.org/vkpurge.8) utility. `vkpurge` comes +pre-installed on every Void Linux system. This utility runs the necessary +[hooks](#kernel-hooks) when removing old kernels. Note that `vkpurge` does not +remove kernel *packages*, only particular *kernels*. + +## Removing the default kernel series + +If you've installed a kernel package for a series other than the default, and +want to remove the default kernel packages, you should install the `linux-base` +package or [mark it as a manual package](https://man.voidlinux.org/xbps-pkgdb.1) +in case it is already installed. After this procedure, you can remove the +default kernel packages with +[xbps-remove(1)](https://man.voidlinux.org/xbps-remove.1). It might be necessary +to add `linux` and `linux-headers` to an `ignorepkg` entry in +[xbps.d(5)](https://man.voidlinux.org/xbps.d.5), since base packages can depend +on them. + +## Switching to another kernel series + +If you'd like to use the `linux-lts` or `linux-mainline` kernel series instead +of the default `linux`, first install the desired series metapackage (and the +`linux-lts-headers` or `linux-mainline-headers` metapackage if needed). Then you +can add `linux` and `linux-headers` to an `ignorepkg` entry in +[xbps.d(5)](https://man.voidlinux.org/xbps.d.5) and uninstall those packages. + +## Changing the default initramfs generator + +By default, EvolutionOS uses [dracut](https://man.voidlinux.org/dracut.8) to +prepare initramfs images for installed kernels. Alternatives such as +[mkinitcpio](https://man.voidlinux.org/mkinitcpio.8) are available. Each +initramfs generator registers an [XBPS +alternative](https://man.voidlinux.org/xbps-alternatives.1) in the `initramfs` +group to link its [kernel hooks](#kernel-hooks) to be used when creating or +removing initramfs images for a given kernel. + +To replace dracut with, *e.g.*, mkinitcpio, install the `mkinitcpio` package; +confirm that `mkinitcpio` appears in the list of available alternatives by +running + +``` +$ xbps-alternatives -l -g initramfs +``` + +Issue the command + +``` +# xbps-alternatives -s mkinitcpio +``` + +to replace the dracut kernel hooks with those provided by mkinitcpio. With +subsequent kernel updates (or updates to DKMS packages that trigger initramfs +regeneration), mkinitcpio will be used instead of dracut to prepare initramfs +images. To force images to regenerate, reconfigure your kernel packages by +invoking + +``` +# xbps-reconfigure -f linux. +``` + +for each `linux.` package that is currently installed. + +## cmdline + +The kernel, the initial RAM disk (initrd) and some system programs can be +configured at boot by kernel command line arguments. The parameters understood +by the kernel are explained in the [kernel-parameters +documentation](https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html) +and by [bootparam(7)](https://man.voidlinux.org/bootparam.7). Parameters +understood by dracut can be found in +[dracut.cmdline(7)](https://man.voidlinux.org/dracut.cmdline.7). + +Once the system is booted, the current kernel command line parameters can be +found in the `/proc/cmdline` file. Some system programs can change their +behavior based on the parameters passed in the command line, which is what +happens when [booting a different +runsvdir](./services/index.md#booting-a-different-runsvdir), for example. + +There are different ways of setting these parameters, some of which are +explained below. + +### GRUB + +Kernel command line arguments can be added through the GRUB bootloader by +editing `/etc/default/grub`, changing the `GRUB_CMDLINE_LINUX_DEFAULT` variable +and then running `update-grub`. + +### dracut + +Dracut offers a [`kernel_cmdline` configuration +option](https://man.voidlinux.org/dracut.conf.5) and [`--kernel-cmdline` +command-line option](https://man.voidlinux.org/dracut.8) that will encode +command-line arguments directly in the initramfs image. When dracut is used to +create a UEFI executable, arguments set with these options will be passed to the +kernel. However, when an ordinary initramfs is produced, these options will +*not* be passed to the kernel at boot. Instead, they will be written to a +configuration file in `/etc/cmdline.d` within the image. While dracut parses +this configuration to control its own boot-time behavior, the kernel itself will +not be aware of anything set via this mechanism. + +After modifying a dracut configuration, [regenerate](#kernel-hooks) the +initramfs to ensure that it includes the changes. + +## Kernel hardening + +EvolutionOS Linux ships with some kernel security options enabled by default. This was +originally provided by kernel command line arguments `slub_debug=P +page_poison=1`, but since kernel series 5.3, these have been replaced with +`init_on_alloc` and `init_on_free` (see [this +commit](https://github.com/torvalds/linux/commit/6471384af)). + +Evolution's kernels come with the `init_on_alloc` option enabled by default where +available (i.e. `linux5.4` and greater). In most cases you should usually not +disable it, as it has a fairly minimal impact on performance (within 1%). The +`init_on_free` option is more expensive (around 5% on average) and needs to be +enabled manually by passing `init_on_free=1` on the kernel command line. If you +need to disable `init_on_alloc`, you can do that similarly by passing +`init_on_alloc=0`. + +There is a chance that your existing system still has the old options enabled. +They still work in newer kernels, but have a performance impact more in line +with `init_on_free=1`. On older hardware this can be quite noticeable. If you +are running a kernel series older than 5.4, you can keep them (or add them) for +extra security at the cost of speed; otherwise you should remove them. + +## Kernel modules + +Kernel modules are typically drivers for devices or filesystems. + +### Loading kernel modules during boot + +Normally the kernel automatically loads required modules, but sometimes it may +be necessary to explicitly specify modules to be loaded during boot. + +To load kernel modules during boot, a `.conf` file like +`/etc/modules-load.d/virtio.conf` needs to be created with the contents: + +``` +# load virtio-net +virtio-net +``` + +### Blacklisting kernel modules + +Blacklisting kernel modules is a method for preventing modules from being loaded +by the kernel. There are two different methods for blacklisting kernel modules, +one for modules loaded by the initramfs and one for modules loaded after the +initramfs process is done. Modules loaded by the initramfs have to be +blacklisted in the initramfs configuration. + +To blacklist modules loaded after the initramfs process, create a `.conf` file, +like `/etc/modprobe.d/radeon.conf`, with the contents: + +``` +blacklist radeon +``` + +#### Blacklisting modules in the initramfs + +After making the necessary changes to the configuration files, the initramfs +needs to be [regenerated](#kernel-hooks) for the changes to take effect on the +next boot. + +##### dracut + +Dracut can be configured to not include kernel modules through a configuration +file. To blacklist modules from being included in a dracut initramfs, create a +`.conf` file, like `/etc/dracut.conf.d/radeon.conf`, with the contents: + +``` +omit_drivers+=" radeon " +``` + +##### mkinitcpio + +To blacklist modules from being included in a mkinitcpio initramfs a `.conf` +file needs to be created like `/etc/modprobe.d/radeon.conf` with the contents: + +``` +blacklist radeon +``` + +## Kernel hooks + +EvolutionOS provides directories for kernel hooks in +`/etc/kernel.d/{pre-install,post-install,pre-remove,post-remove}`. + +These hooks are used to update the boot menus for bootloaders like `grub`, +`gummiboot` and `lilo`. + +### Install hooks + +The `{pre,post}-install` hooks are executed by +[xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) when +configuring a Linux kernel, such as building its initramfs. This happens when a +kernel series is installed for the first time or updated, but can also be run +manually: + +``` +# xbps-reconfigure --force linux. +``` + +If run manually, they serve to apply initramfs configuration changes to the next +boot. + +### Remove hooks + +The `{pre,post}-remove` hooks are executed by +[vkpurge(8)](https://man.voidlinux.org/vkpurge.8) when removing old kernels. + +## Dynamic Kernel Module Support (DKMS) + +There are kernel modules that are not part of the Linux source tree that are +built at install time using DKMS and [kernel hooks](#kernel-hooks). The +available modules can be listed by searching for `dkms` in the package +repositories. + +DKMS build logs are available in `/var/lib/dkms/`. diff --git a/src/config/locales.md b/src/config/locales.md new file mode 100644 index 0000000..b116fa5 --- /dev/null +++ b/src/config/locales.md @@ -0,0 +1,30 @@ +# Locales and Translations + +For a list of currently enabled locales, run + +``` +$ locale -a +``` + +## Enabling locales + +To enable a certain locale, un-comment or add the relevant lines in +`/etc/default/libc-locales` and [force-reconfigure](../xbps/index.md) the +`glibc-locales` package. + +## Setting the system locale + +Set `LANG=xxxx` in `/etc/locale.conf`. + +## Application locale + +Some programs have their translations in a separate package that must be +installed in order to use them. You can +[search](../xbps/index.md#finding-files-and-packages) for the desired language +(e.g. "german" or "portuguese") in the package repositories and install the +packages relevant to the applications you use. An especially relevant case is +when installing individual packages from the LibreOffice suite, such as +`libreoffice-writer`, which require installing at least one of the +`libreoffice-i18n-*` packages to work properly. This isn't necessary when +installing the `libreoffice` meta-package, since doing so will install the most +common translation packages. diff --git a/src/config/media/alsa.md b/src/config/media/alsa.md new file mode 100644 index 0000000..670d2a2 --- /dev/null +++ b/src/config/media/alsa.md @@ -0,0 +1,55 @@ +# ALSA + +To use ALSA, install the `alsa-utils` package and make sure your user is a +member of the `audio` group. + +The `alsa-utils` package provides the `alsa` service. When enabled, this service +saves and restores the state of ALSA (e.g. volume) at shutdown and boot, +respectively. + +To allow use of software requiring PulseAudio, install the `apulse` package. +`apulse` provides part of the PulseAudio interface expected by applications, +translating calls to that interface into calls to ALSA. For details about using +`apulse`, consult [the project +README](https://github.com/i-rinat/apulse/blob/master/README.md). + +## Configuration + +The default sound card can be specified via ALSA configuration files or via +kernel module options. + +To obtain information about the order of loaded sound card modules: + +``` +$ cat /proc/asound/modules + 0 snd_hda_intel + 1 snd_hda_intel + 2 snd_usb_audio +``` + +To set a different card as the default, edit `/etc/asound.conf` or the per-user +configuration file `~/.asoundrc`: + +``` +defaults.ctl.card 2; +defaults.pcm.card 2; +``` + +or specify sound card module order in `/etc/modprobe.d/alsa.conf`: + +``` +options snd_usb_audio index=0 +``` + +## Dmix + +The `dmix` ALSA plugin allows playing sound from multiple sources. `dmix` is +enabled by default for soundcards which do not support hardware mixing. To +enable it for digital output, edit `/etc/asound.conf`: + +``` +pcm.dsp { + type plug + slave.pcm "dmix" +} +``` diff --git a/src/config/media/index.md b/src/config/media/index.md new file mode 100644 index 0000000..e6dbd8f --- /dev/null +++ b/src/config/media/index.md @@ -0,0 +1,13 @@ +# Multimedia + +## Audio setup + +To setup audio on your EvolutionOS system you have to decide if you want to use +[PulseAudio](./pulseaudio.md), [PipeWire](./pipewire.md) or just +[ALSA](./alsa.md). + +Some applications require PulseAudio, especially closed source programs, but +[PipeWire](./pipewire.md) provides a drop-in replacement for PulseAudio. + +If [elogind](../session-management.md) is not enabled, it is necessary to be in +the `audio` group in order to have access to audio devices. diff --git a/src/config/media/pipewire.md b/src/config/media/pipewire.md new file mode 100644 index 0000000..458aee0 --- /dev/null +++ b/src/config/media/pipewire.md @@ -0,0 +1,172 @@ +# PipeWire + +To use PipeWire, install the `pipewire` package. + +[pipewire(1)](https://man.voidlinux.org/pipewire.1) should be started as a user. +Run the pipewire command in a terminal emulator in your session. + +``` +$ pipewire +``` + +When pipewire works as expected, use the autostarting mechanism of your desktop +environment or [startx](../graphical-session/xorg.md#startx). The `pipewire` +package ships [Desktop +Entry](https://specifications.freedesktop.org/desktop-entry-spec/latest/) files +for `pipewire` and `pipewire-pulse` in `/usr/share/applications`. If your +environment supports the [Desktop Application Autostart +Specification](https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html), +you can enable pipewire by symlinking the desktop files to the autostart +directory: + +``` +# ln -s /usr/share/applications/pipewire.desktop /etc/xdg/autostart/pipewire.desktop +``` + +## Session Management + +In PipeWire, a session manager assumes responsibility for interconnecting media +sources and sinks as well as enforcing routing policy. Without a session +manager, PipeWire will not function. The reference +[`pipewire-media-session`](https://gitlab.freedesktop.org/pipewire/media-session) +was originally provided in the EvolutionOS `pipewire` package and configured to run by +default to satisfy this requirement. However, `pipewire-media-session` is +deprecated and the authors recommend using +[WirePlumber](https://pipewire.pages.freedesktop.org/wireplumber/) in its place. +Install the `wireplumber` package to use this session manager with PipeWire. + +> If you have installed an earlier version of the EvolutionOS `pipewire` package, make +> sure to update your system to eliminate any stale system configuration that +> may attempt to launch `pipewire-media-session`. Users who previously overrode +> the system configuration to use `wireplumber`, *e.g.* by placing a custom +> `pipewire.conf` file in `/etc/pipewire` or `${XDG_CONFIG_HOME}/pipewire`, may +> wish to reconcile these overrides with `/usr/share/pipewire/pipewire.conf` +> installed by the most recent `pipewire` package. If the sole purpose of a +> prior override was to disable `pipewire-media-session`, deleting the custom +> configuration may be sufficient. + +There are several methods for starting `wireplumber` alongside `pipewire`. If +your window manager or desktop environment auto-start mechanism is used to start +`pipewire`, it is recommended to use the same mechanism for starting +`wireplumber`. The `wireplumber` package includes a `wireplumber.desktop` +Desktop Entry file that may be useful in this situation. + +> Be aware that `wireplumber` must launch *after* the `pipewire` executable. The +> Desktop Application Autostart Specification makes no provision for ordering of +> services started via Desktop Entry files. When relying on these files to +> launch `pipewire` and `wireplumber`, consult the documentation for your window +> manager or desktop environment to determine whether proper ordering of +> services can be achieved. + +If proper ordering of separate `pipewire` and `wireplumber` services is +infeasible, it is possible to configure `pipewire` to launch the session manager +directly. This can be accomplished by running + +``` +# mkdir -p /etc/pipewire/pipewire.conf.d +# ln -s /usr/share/examples/wireplumber/10-wireplumber.conf /etc/pipewire/pipewire.conf.d/ +``` + +for system configurations or, for per-user configurations, running + +``` +$ true "${XDG_CONFIG_HOME:=${HOME}/.config}" +$ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d" +# ln -s /usr/share/examples/wireplumber/10-wireplumber.conf "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/" +``` + +With either of these configurations, launching `pipewire` should be sufficient +to establish a working PipeWire session that uses `wireplumber` for session +management. + +In its default configuration, WirePlumber requires an active [D-Bus +session](../session-management.md#d-bus). If your desktop environment or window +manager is configured to provide a D-Bus session as well as launch `pipewire` +and `wireplumber`, no further configuration should be required. Users wishing to +launch `pipewire` on its own, *e.g.*, in a `.xinitrc` script, may find it +necessary to configure `pipewire` to launch `wireplumber` directly and wrap the +`pipewire` invocation as + +``` +dbus-run-session pipewire +``` + +## PulseAudio replacement + +Before starting `pipewire-pulse`, make sure that the PulseAudio service is +[disabled](../services/index.md#disabling-services) and that no other PulseAudio +server instance is running. + +Start the PulseAudio server by running `pipewire-pulse` in a terminal emulator. + +To check if the replacement is working correctly, use +[pactl(1)](https://man.voidlinux.org/pactl.1) (provided by the +`pulseaudio-utils` package): + +``` +$ pactl info + +[...] +Server Name: PulseAudio (on PipeWire 0.3.18) +[...] +``` + +Once you confirmed that `pipewire-pulse` works as expected, it's recommended to +autostart it from the same place where you start PipeWire. Alternatively, the +`pipewire` configuration can be modified to launch `pipewire-pulse` directly: + +``` +# mkdir -p /etc/pipewire/pipewire.conf.d +# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf /etc/pipewire/pipewire.conf.d/ +``` + +for system configurations, or + +``` +$ true "${XDG_CONFIG_HOME:=${HOME}/.config}" +$ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d" +# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/" +``` + +for per-user configurations. + +## Bluetooth audio + +For bluetooth audio to work, install the `libspa-bluetooth` package. + +## ALSA integration + +Install `alsa-pipewire`, then enable the PipeWire ALSA device and make it the +default: + +``` +# mkdir -p /etc/alsa/conf.d +# ln -s /usr/share/alsa/alsa.conf.d/50-pipewire.conf /etc/alsa/conf.d +# ln -s /usr/share/alsa/alsa.conf.d/99-pipewire-default.conf /etc/alsa/conf.d +``` + +## JACK replacement + +Install `libjack-pipewire`. + +Use [pw-jack(1)](https://man.voidlinux.org/pw-jack.1) to launch JACK clients +manually: + +``` +$ pw-jack +``` + +Alternatively, override the library provided by `libjack` (see +[ld.so(8)](https://man.voidlinux.org/ld.so.8)). The following approach will work +on glibc-based systems: + +``` +# echo "/usr/lib/pipewire-0.3/jack" > /etc/ld.so.conf.d/pipewire-jack.conf +# ldconfig +``` + +## Troubleshooting + +The PulseAudio replacement requires the +[`XDG_RUNTIME_DIR`](../session-management.html#xdg_runtime_dir) environment +variable to work correctly. diff --git a/src/config/media/pulseaudio.md b/src/config/media/pulseaudio.md new file mode 100644 index 0000000..0a06ee9 --- /dev/null +++ b/src/config/media/pulseaudio.md @@ -0,0 +1,26 @@ +# PulseAudio + +Depending on which applications you use, you might need to provide PulseAudio +with a D-BUS session bus (e.g. via `dbus-run-session`) or a D-BUS system bus +(via the `dbus` service). + +For applications which use ALSA directly and don't support PulseAudio, the +`alsa-plugins-pulseaudio` package can make them use PulseAudio through ALSA. + +PulseAudio will automatically start when needed. If it is not starting +automatically, it can be started manually by invoking +[pulseaudio(1)](https://man.voidlinux.org/pulseaudio.1) from the terminal as +follows: + +``` +$ pulseaudio --daemonize=no --exit-idle-time=-1 +``` + +On the other hand, PulseAudio can also end up being auto activated when it isn't +desired. To inhibit this behavior, the `autospawn` directive from +[pulse-client.conf(5)](https://man.voidlinux.org/pulse-client.conf.5) can be set +to `no`. + +There are several methods of allowing PulseAudio to access to audio devices. The +simplest one is to add your user to the `audio` group. Alternatively, you can +use a session manager, like `elogind`. diff --git a/src/config/media/sndio.md b/src/config/media/sndio.md new file mode 100644 index 0000000..ecd6e48 --- /dev/null +++ b/src/config/media/sndio.md @@ -0,0 +1,61 @@ +# sndio + +Install the `sndio` package and enable the +[sndiod(8)](https://man.voidlinux.org/sndiod.8) service. + +## Configuration + +The service can be configured by adding +[sndiod(8)](https://man.voidlinux.org/sndiod.8) flags to the `OPTS` variable in +the service configuration file (`/etc/sv/sndiod/conf`). + +### Default device + +[sndiod(8)](https://man.voidlinux.org/sndiod.8) uses the first ALSA device by +default. To use another ALSA device for sndio's default device `snd/0` add the +flags to use specific devices to the service configuration file. + +``` +# echo 'OPTS="-f rsnd/Speaker"' >/etc/sv/sndiod/conf +``` + +Use the `-f` flag to chooses a device by its ALSA device index or its ALSA +device name. + +## Volume control + +The master and per application volume controls are controlled with MIDI messages +by hardware or software. + +[aucatctl(1)](https://man.voidlinux.org/aucatctl.1) is a tool specific to sndio +to send MIDI control messages to the +[sndiod(8)](https://man.voidlinux.org/sndiod.8) daemon. It can be found in the +`aucatctl` package. + +## Application specific configurations + +### Firefox + +Firefox is built with sndio support and should work out of the box since version +71 if libsndio is installed and the `snd/0` device is available. + +The following `about:config` changes are required for versions prior to 71 and +should be removed when using version 71 or later: + +``` +media.cubeb.backend;sndio +media.cubeb.sandbox;false +security.sandbox.content.read_path_whitelist;/home//.sndio/cookie +security.sandbox.content.write_path_whitelist;/home//.sndio/cookie +``` + +### OpenAL + +libopenal comes with sndio support, but prioritizes ALSA over sndio by default. +You can configure this behavior per user in `~/.alsoftrc` or system wide in +`/etc/openal/alsoft.conf` by adding the following lines: + +``` +[general] +drivers = sndio +``` diff --git a/src/config/network-filesystems.md b/src/config/network-filesystems.md new file mode 100644 index 0000000..6ccc11d --- /dev/null +++ b/src/config/network-filesystems.md @@ -0,0 +1,71 @@ +# Network Filesystems + +## NFS + +### Mounting an NFS Share + +To mount an NFS share, start by installing the `nfs-utils` and `sv-netmount` +packages. + +Before mounting an NFS share, [enable](./services/index.md#enabling-services) +the `statd`, `rpcbind`, and `netmount` services. If the server supports `nfs4`, +the `statd` service isn't necessary. + +To mount an NFS share: + +``` +# mount -t :/path/to/sourcedir /path/to/destdir +``` + +`` should be `nfs4` if the server supports it, or `nfs` otherwise. +`` can be either the hostname or IP address of the server. + +Mounting options can be found in +[mount.nfs(8)](https://man.voidlinux.org/mount.nfs.8), while unmounting options +can be found in [umount.nfs(8)](https://man.voidlinux.org/umount.nfs.8). + +For example, to connect `/volume` on a server at `192.168.1.99` to an existing +`/mnt/volume` directory on your local system: + +``` +# mount -t nfs 192.168.1.99:/volume /mnt/volume +``` + +To have the directory mounted when the system boots, add an entry to +[fstab(5)](https://man.voidlinux.org/fstab.5): + +``` +192.168.1.99:/volume /mnt/volume nfs rw,hard 0 0 +``` + +Refer to [nfs(5)](https://man.voidlinux.org/nfs.5) for information about the +available mounting options. + +### Setting up a server (NFSv4, Kerberos disabled) + +To run an NFS server, start by installing the `nfs-utils` package. + +Edit `/etc/exports` to add a shared volume: + +``` +/storage/foo *.local(rw,no_subtree_check,no_root_squash) +``` + +This line exports the `/storage/foo` directory to any host in the local domain, +with read/write access. For information about the `no_subtree_check` and +`no_root_squash` options, and available options more generally, refer to +[exports(5)](https://man.voidlinux.org/exports.5). + +Finally, [enable](./services/index.md#enabling-services) the `rpcbind`, `statd`, +and `nfs-server` services. + +This will start your NFS server. To check if the shares are working, use the +[showmount(8)](https://man.voidlinux.org/showmount.8) utility to check the NFS +server status: + +``` +# showmount -e localhost +``` + +You can use [nfs.conf(5)](https://man.voidlinux.org/nfs.conf.5) to configure +your server. diff --git a/src/config/network/connman.md b/src/config/network/connman.md new file mode 100644 index 0000000..031300c --- /dev/null +++ b/src/config/network/connman.md @@ -0,0 +1,50 @@ +# ConnMan + +[ConnMan(8)](https://man.voidlinux.org/connman.8) is a daemon that manages +network connections, is designed to be slim and to use as few resources as +possible. The `connman` package contains the basic utilities to run ConnMan. + +## Starting ConnMan + +To enable the ConnMan daemon, first [disable](../services/index.md) any other +network managing services like [dhcpcd](./index.md#dhcpcd), +[wpa_supplicant](./wpa_supplicant.md), or `wicd`. These services all control +network interface configuration, and interfere with each other. + +Finally, enable the `connmand` service. + +## Configuring ConnMan + +### ConnMan CLI + +The `connman` package includes a command line tool, +[connmanctl(1)](https://man.voidlinux.org/connmanctl.1) to control network +settings. If you do not provide any commands, `connmanctl` starts as an +interactive shell. + +Establishing a connection to an access point using the `connmanctl` interactive +shell might look as follows: + +``` +# connmanctl +> enable wifi +> agent on +> scan wifi +> services +> connect wifi_ +> exit +``` + +### ConnMan Front-End Tools + +There are many other front-ends to ConnMan, including `connman-ui` for system +trays, `connman-gtk` for GTK, `cmst` for QT and `connman-ncurses` for ncurses +based UI. + +## Preventing DNS overrides by ConnMan + +Create `/etc/sv/connmand/conf` with the following content: + +``` +OPTS="--nodnsproxy" +``` diff --git a/src/config/network/firewalls.md b/src/config/network/firewalls.md new file mode 100644 index 0000000..5a0309e --- /dev/null +++ b/src/config/network/firewalls.md @@ -0,0 +1,92 @@ +# Firewalls + +## iptables + +By default, the `iptables` package is installed on the base system. It provides +[iptables(8)/ip6tables(8)](https://man.voidlinux.org/iptables.8). The related +services use the `/etc/iptables/iptables.rules` and +`/etc/iptables/ip6tables.rules` ruleset files, which must be created by the +system administrator. + +Two example rulesets are provided in the `/etc/iptables` directory: +`empty.rules` and `simple_firewall.rules`. + +### Applying the rules at boot + +To apply iptables rules at runit stage 1, install the `runit-iptables` package. +This adds a core-service which restores the `iptables.rules` and +`ip6tables.rules` rulesets. + +Alternatively, to apply these rules at stage 2, add the following to +`/etc/rc.local`: + +``` +if [ -e /etc/iptables/iptables.rules ]; then + iptables-restore /etc/iptables/iptables.rules +fi + +if [ -e /etc/iptables/ip6tables.rules ]; then + ip6tables-restore /etc/iptables/ip6tables.rules +fi +``` + +After rebooting, check the active firewall rules: + +``` +# iptables -L +# ip6tables -L +``` + +### Applying the rules at runtime + +`iptables` comes with two runit services, `iptables` and `ip6tables`, to quickly +flush or restore the `iptables.rules` and `ip6tables.rules` rulesets. Once these +services are [enabled](../services/index.md#enabling-services), you can flush +the rulesets by downing the relevant service, e.g.: + +``` +# sv down iptables +``` + +and restore them by upping the relevant service, e.g.: + +``` +# sv up ip6tables +``` + +## nftables + +`nftables` replaces `iptables`, `ip6tables`, `arptables` and `ebtables` +(collectively referred to as `xtables`). The [nftables +wiki](https://wiki.nftables.org/wiki-nftables/index.php/Main_Page) describes +[the main +differences](https://wiki.nftables.org/wiki-nftables/index.php/Main_differences_with_iptables) +from the `iptables` toolset. + +To use `nftables`, install the `nftables` package, which provides +[nft(8)](https://man.voidlinux.org/nft.8). It also provides +[iptables-translate(8)/ip6tables-translate(8)](https://man.voidlinux.org/iptables-translate.8) +and +[iptables-restore-translate(8)/ip6tables-restore-translate(8)](https://man.voidlinux.org/iptables-restore-translate.8), +which convert `iptables` rules to `nftables` rules. + +### Applying the rules at boot + +To apply nftables rules at runit stage 1, install the `runit-nftables` package. +This adds a core-service which restores the ruleset in `/etc/nftables.conf`. + +### Applying the rules at runtime + +The `nftables` package provides the `nftables` service, which uses rules from +`/etc/nftables.conf`. Once you [enable](../services/index.md#enabling-service) +the `nftables` service, to load the rules, run: + +``` +# sv up nftables +``` + +To flush the rules, run: + +``` +# sv down nftables +``` diff --git a/src/config/network/index.md b/src/config/network/index.md new file mode 100644 index 0000000..be9f1e4 --- /dev/null +++ b/src/config/network/index.md @@ -0,0 +1,71 @@ +# Network + +Network configuration in EvolutionOS can be done in several ways. The default +installation comes with the [dhcpcd(8)](https://man.voidlinux.org/dhcpcd.8) +service enabled. + +## Interface Names + +Newer versions of [udev(7)](https://man.voidlinux.org/udev.7) no longer use the +traditional Linux naming scheme for interfaces (`eth0`, `eth1`, `wlan0`, ...). + +This behavior can be reverted by adding `net.ifnames=0` to the [kernel +cmdline](../kernel.md#cmdline). + +## Static Configuration + +A simple way to configure a static network at boot is to add the necessary +[ip(8)](https://man.voidlinux.org/ip.8) commands to the `/etc/rc.local` file: + +``` +ip link set dev eth0 up +ip addr add 192.168.1.2/24 brd + dev eth0 +ip route add default via 192.168.1.1 +``` + +## Bridge Interfaces + +To configure bridge interfaces at boot, the `/etc/rc.local` file can be used to +run [ip(8)](https://man.voidlinux.org/ip.8) commands to add the bridge `br0` and +set it as the master for the `eth0` interface as example: + +``` +ip link add name br0 type bridge +ip link set eth0 master br0 +ip link set eth0 up +``` + +## dhcpcd + +To run [dhcpcd(8)](https://man.voidlinux.org/dhcpcd.8) on all interfaces, enable +the `dhcpcd` service. + +To run `dhcpcd` only on a specific interface, copy the `dhcpcd-eth0` service and +modify it to match your interface: + +``` +$ ip link show +1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: enp3s0: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether ff:ff:ff:ff:ff:ff brd ff:ff:ff:f +# cp -R /etc/sv/dhcpcd-eth0 /etc/sv/dhcpcd-enp3s0 +# sed -i 's/eth0/enp3s0/' /etc/sv/dhcpcd-enp3s0/run +# ln -s /etc/sv/dhcpcd-enp3s0 /var/service/ +``` + +For more information on configuring `dhcpcd`, refer to +[dhcpcd.conf(5)](https://man.voidlinux.org/dhcpcd.conf.5) + +## Wireless + +Before using wireless networking, use +[rfkill(8)](https://man.voidlinux.org/rfkill.8) to check whether the relevant +interfaces are soft- or hard-blocked. + +EvolutionOS provides several ways to connect to wireless networks: + +- [wpa_supplicant](./wpa_supplicant.md) +- [iwd](./iwd.md) +- [NetworkManager](./networkmanager.md) +- [ConnMan](./connman.md) diff --git a/src/config/network/iwd.md b/src/config/network/iwd.md new file mode 100644 index 0000000..92042a4 --- /dev/null +++ b/src/config/network/iwd.md @@ -0,0 +1,73 @@ +# IWD + +[IWD](https://iwd.wiki.kernel.org/) (iNet Wireless Daemon) is a wireless daemon +for Linux that aims to replace [WPA supplicant](./wpa_supplicant.md). + +## Installation + +Install the `iwd` package and enable the `dbus` and `iwd` services. + +## Usage + +The command-line client [iwctl(1)](https://man.voidlinux.org/iwctl.1) can be +used to add, remove, and configure network connections. Commands can be passed +as arguments; when run without arguments, it provides an interactive session. To +list available commands, run `iwctl help`, or run `iwctl` and enter `help` at +the interactive prompt. + +By default, only the root user and those in the `wheel` group have permission to +operate `iwctl`. + +## Configuration + +Configuration options and examples are described below. Consult the relevant +manual pages and the [upstream +documentation](https://iwd.wiki.kernel.org/networkconfigurationsettings) for +further information. + +### Daemon configuration + +The main configuration file is located in `/etc/iwd/main.conf`. If it does not +exist, you may create it. It is documented in +[iwd.config(5)](https://man.voidlinux.org/iwd.config.5). + +### Network configuration + +Network configuration, including examples, is documented in +[iwd.network(5)](https://man.voidlinux.org/iwd.network.5). IWD stores +information on known networks, and reads information on pre-provisioned networks +from network configuration files located in `/var/lib/iwd`; IWD monitors the +directory for changes. Network configuration filenames consist of the encoding +of the SSID followed by `.open`, `.psk`, or `.8021x` as determined by the +security type. + +As an example, a basic configuration file for a WPA2/PSK secured network would +be called `.psk`, and it would contain the plain text password: + +``` +[Security] +Passphrase= +``` + +## Troubleshooting + +By default, IWD will create and destroy the wireless interfaces (e.g. `wlan0`) +that it manages. This can interfere with `udevd`, which may attempt to rename +the interface using its rules for persistent network interface names. The +following messages may be printed to your screen as a symptom of this +interference: + +``` +[ 39.441723] udevd[1100]: Error changing net interface name wlan0 to wlp59s0: Device or resource busy +[ 39.442472] udevd[1100]: could not rename interface '3' from 'wlan0' to 'wlp59s0': Device or resource busy +``` + +A simple fix is to prevent IWD from manipulating the network interfaces in this +way by adding `UseDefaultInterface=true` to the `[General]` section of +`/etc/iwd/main.conf`. + +An alternative approach is to disable the use of persistent network interface +names by `udevd`. This may be accomplished either by adding `net.ifnames=0` to +your kernel [cmdline](../kernel.md#cmdline) or by creating a symbolic link to +`/dev/null` at `/etc/udev/rules.d/80-net-name-slot.rules` to mask the renaming +rule. This alternative approach will affect the naming of all network devices. diff --git a/src/config/network/networkmanager.md b/src/config/network/networkmanager.md new file mode 100644 index 0000000..41b40c9 --- /dev/null +++ b/src/config/network/networkmanager.md @@ -0,0 +1,46 @@ +# NetworkManager + +[NetworkManager(8)](https://man.voidlinux.org/NetworkManager.8) is a daemon that +manages Ethernet, Wi-Fi, and mobile broadband network connections. Install the +`NetworkManager` package for the basic NetworkManager utilities. + +## Starting NetworkManager + +Before enabling the NetworkManager daemon, [disable](../services/index.md) any +other network management services, such as [dhcpcd](./index.md#dhcpcd), +[wpa_supplicant](./wpa_supplicant.md), or `wicd`. These services all control +network interface configuration, and will interfere with NetworkManager. + +Also ensure that the `dbus` service is [enabled](../services/index.md) and +running. NetworkManager uses `dbus` to expose networking information and a +control interface to clients, and will fail to start without it. + +Finally, enable the `NetworkManager` service. + +## Configuring NetworkManager + +Users of NetworkManager must belong to the `network` group. + +The `NetworkManager` package includes a command line tool, +[nmcli(1)](https://man.voidlinux.org/nmcli.1), and a text-based user interface, +[nmtui(1)](https://man.voidlinux.org/nmtui.1), to control network settings. + +There are many other front-ends to NetworkManager, including `nm-applet` for +system trays, `nm-plasma` for KDE Plasma, and a built-in network configuration +tool in GNOME. + +## Eduroam with NetworkManager + +Eduroam is a roaming service providing international, secure Internet access at +universities and other academic institutions. More information can be found +[here](https://eduroam.org/). + +### Dependencies + +Install the `python3-dbus` package. + +### Installation + +Download the correct eduroam_cat installer for your institution from +[here](https://cat.eduroam.org/) and execute it. It will provide a user +interface guiding you through the process. diff --git a/src/config/network/wpa_supplicant.md b/src/config/network/wpa_supplicant.md new file mode 100644 index 0000000..d4e868e --- /dev/null +++ b/src/config/network/wpa_supplicant.md @@ -0,0 +1,87 @@ +# wpa_supplicant + +The `wpa_supplicant` package is installed by default on the base system. It +includes utilities to configure wireless interfaces and handle wireless security +protocols. To use wpa_supplicant, you will need to enable [the wpa_supplicant +service](#the-wpa_supplicant-service). + +[wpa_supplicant(8)](https://man.voidlinux.org/wpa_supplicant.8) is a daemon that +manages wireless interfaces based on +[wpa_supplicant.conf(5)](https://man.voidlinux.org/wpa_supplicant.conf.5) +configuration files. An extensive overview of configuration options, including +examples, can be found in +`/usr/share/examples/wpa_supplicant/wpa_supplicant.conf`. + +[wpa_passphrase(8)](https://man.voidlinux.org/wpa_passphrase.8) helps create +pre-shared keys for use in configuration files. +[wpa_cli(8)](https://man.voidlinux.org/wpa_cli.8) provides a CLI for managing +the `wpa_supplicant` daemon. + +## WPA-PSK + +To use WPA-PSK, generate a pre-shared key with +[wpa_passphrase(8)](https://man.voidlinux.org/wpa_passphrase.8) and append the +output to the relevant `wpa_supplicant.conf` file: + +``` +# wpa_passphrase >> /etc/wpa_supplicant/wpa_supplicant-.conf +``` + +## WPA-EAP + +WPA-EAP is often used for institutional logins, notably eduroam. This does not +use PSK, but a password hash can be generated like this: + +``` +$ echo -n | iconv -t utf16le | openssl md4 +``` + +## WEP + +For WEP configuration, add the following lines to your device's +`wpa-supplicant.conf`: + +``` +network={ + ssid="MYSSID" + key_mgmt=NONE + wep_key0="YOUR AP WEP KEY" + wep_tx_keyidx=0 + auth_alg=SHARED +} +``` + +### The wpa_supplicant service + +The `wpa_supplicant` service checks the following options in +`/etc/sv/wpa_supplicant/conf`: + +- `OPTS`: Options to be passed to the service. Overrides any other options. +- `CONF_FILE`: Path to file to be used for configuration. Defaults to + `/etc/wpa_supplicant/wpa_supplicant.conf`. +- `WPA_INTERFACE`: Interface to be matched. May contain a wildcard; defaults to + all interfaces. +- `DRIVER`: Driver to use. See `wpa_supplicant -h` for available drivers. + +If no `conf` file is found, the service searches for the following files in +`/etc/wpa_supplicant`: + +- `wpa_supplicant-.conf`: If found, these files are bound to the + named interface. +- `wpa_supplicant.conf`: If found, this file is loaded and binds to all other + interfaces found. + +Once you are satisfied with your configuration, +[enable](../services/index.md#enabling-services) the `wpa_supplicant` service. + +### Using wpa_cli + +When using `wpa_cli` to manage `wpa_supplicant` from the command line, be sure +to specify which network interface to use via the `-i` option, e.g.: + +``` +# wpa_cli -i wlp2s0 +``` + +Not doing so can result in various `wpa_cli` commands (for example, `scan` and +`scan_results`) not producing the expected output. diff --git a/src/config/openpgp.md b/src/config/openpgp.md new file mode 100644 index 0000000..484e96d --- /dev/null +++ b/src/config/openpgp.md @@ -0,0 +1,34 @@ +# GnuPG + +EvolutionOS ships both GnuPG legacy (as `gnupg1`) and GnuPG stable (as `gnupg`). + +## Smartcards + +For using smartcards such as Yubikeys with GnuPG, there are two backends for +communicating with them through GnuPG: The internal CCID driver of GnuPG's +scdaemon, or the PC/SC driver. + +## scdaemon with internal CCID driver + +By default, scdaemon, which is required for using smartcards with GnuPG, uses +its internal CCID driver. For this to work, your smartcard needs to be one of +the smartcards in the udev rules +[here](https://github.com/void-linux/void-packages/blob/master/srcpkgs/gnupg/files/60-scdaemon.rules) +and you need to either be using elogind or be a member of the plugdev group. If +these two condition are fulfilled and you don't have pcscd running, `gpg +--card-status` should successfully print your current card status. + +## scdaemon with pcscd backend + +If you need to use pcscd for other reasons, run `echo disable-ccid >> +~/.gnupg/scdaemon.conf`. Now, assuming your pcscd setup works correctly, `gpg +--card-status` should print your card status. + +# OpenPGP Card Tools + +As an alternative to GnuPG with smartcards, EvolutionOS also ships +`openpgp-card-tools`, a Rust based utility not reliant on GnuPG. It requires +using `pcscd` for interacting with smart cards, so if you want to use it in +parallel with GnuPG, ou need to configure `scdaemon` to use the pcscd backend, +as described above in "[scdaemon with pcscd +backend](#scdaemon-with-pcscd-backend)". diff --git a/src/config/package-documentation/index.md b/src/config/package-documentation/index.md new file mode 100644 index 0000000..02c1d8c --- /dev/null +++ b/src/config/package-documentation/index.md @@ -0,0 +1,16 @@ +# Package Documentation + +The most common media for documentation in EvolutionOS are [manual +pages](./man.md). + +Many packages contain documentation in other formats, like HTML. This +documentation can usually be found in a `/usr/share/doc/` directory. + +More extensive documentation may be split into separate `*-doc` packages, such +as `julia-doc`. This is often the case for programming languages, databases and +big software libraries. + +In addition to documentation provided by upstream projects, packages may also +contain description of initial setup or usage specific to EvolutionOS, provided by +distribution contributors. It will be located in +`/usr/share/doc//README.voidlinux`. diff --git a/src/config/package-documentation/man.md b/src/config/package-documentation/man.md new file mode 100644 index 0000000..5c8f572 --- /dev/null +++ b/src/config/package-documentation/man.md @@ -0,0 +1,77 @@ +# Manual Pages + +Many EvolutionOS packages come with manual ('man') pages. The default installation +includes the [mandoc](https://mandoc.bsd.lv/) manpage toolset, via the `mdocml` +package. + +The [man(1)](https://man.voidlinux.org/man.1) command can be used to show man +pages: + +``` +$ man chroot +``` + +Every man page belongs to a particular *section*: + +- 1: User commands (Programs) +- 2: System calls +- 3: Library calls +- 4: Special files (devices) +- 5: File formats and configuration files +- 6: Games +- 7: Overview, conventions, and miscellaneous +- 8: System management commands + +Refer to [man-pages(7)](https://man.voidlinux.org/man-pages.7) for details. + +There are some man pages which have the same name, but are used in different +contexts, and are thus in a different section. You can specify which one to use +by including the section number in the call to `man`: + +``` +$ man 1 printf +``` + +`man` can be configured via [man.conf(5)](https://man.voidlinux.org/man.conf.5). + +The `mandoc` toolset contains [apropos(1)](https://man.voidlinux.org/apropos.1), +which can be used to search for manual pages. `apropos` uses a database that can +be generated and updated with the +[makewhatis(8)](https://man.voidlinux.org/makewhatis.8) command: + +``` +# makewhatis +$ apropos chroot +chroot(1) - run command or interactive shell with special root directory +xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces +xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces +chroot(2) - change root directory +``` + +The `mdocml` package provides a cron job to update the database daily, +`/etc/cron.daily/makewhatis`. You will need to install and enable a [cron +daemon](../cron.md) for this functionality to be activated. + +Development and POSIX manuals are not installed by default, but are available +via the `man-pages-devel` and `man-pages-posix` packages. + +## Localized manual pages + +It is also possible to use localized man pages from packages which provide their +own as well as those provided by the `manpages-*` packages. However, this can +require some configuration. + +### With mdocml + +If `mdocml` is being used and the settings should be applied for all users, it +is necessary to add the relevant paths to +[man.conf(5)](https://man.voidlinux.org/man.conf.5). For example, German +speakers would add these two lines to their configuration file: + +``` +/usr/share/man/de +/usr/share/man/de.UTF-8 +``` + +Alternatively, each user can export the `MANPATH` variable in their environment, +as explained in [man(1)](https://man.voidlinux.org/man.1). diff --git a/src/config/php.md b/src/config/php.md new file mode 100644 index 0000000..8be6827 --- /dev/null +++ b/src/config/php.md @@ -0,0 +1,35 @@ +# PHP + +There are two ways to install PHP packages with XBPS: + +1. Using the versioned packages (recommended). +2. Using the meta-packages. + +## Versioned PHP Packages + +It is generally recommended to use versioned PHP packages (e.g. `php8.1`, +`php8.1-apcu`, etc.) for most use cases as this ensures a consistent environment +on updates with minimal or no intervention required. + +## PHP Meta-packages + +In EvolutionOS, the `php` package is a meta-package that points to the latest upstream +PHP version. This convention is followed by all packages prefixed with `php-`, +such as `php-fpm`, as well as `xdebug` and `composer`. See [the `php` +template](https://github.com/void-linux/void-packages/blob/master/srcpkgs/php/template) +for a complete list. It is recommended to only use these meta-packages for +development purposes. + +When using a PHP meta-package, be warned that updating may require manual +intervention if a new major PHP version has been added to the repository. As a +part of the version change, the configuration location will change to reflect +the new version. For example, upgrading from 8.0 to 8.1 would result in the +configuration path changing from `/etc/php8.0` to `/etc/php8.1`. Any +customizations that have been made need to be manually applied to the new +configuration directory. + +`php-fpm` updates require special care since they include a runit service. In +this case, ensure that the new runit service is started and that applications +using the previous version of `php-fpm` can access the new `php-fpm` instance. +In particular, make sure any applications accessing the FPM instance have the +correct TCP/unix socket address. diff --git a/src/config/power-management.md b/src/config/power-management.md new file mode 100644 index 0000000..fcf7be8 --- /dev/null +++ b/src/config/power-management.md @@ -0,0 +1,26 @@ +# Power Management + +## acpid + +The `acpid` service for [acpid(8)](https://man.voidlinux.org/acpid.8) is +installed. ACPI events are handled by `/etc/acpi/handler.sh`, which uses +[zzz(8)](https://man.voidlinux.org/zzz.8) for suspend-to-RAM events. + +## elogind + +The `elogind` service is provided by the `elogind` package. By default, +[elogind(8)](https://man.voidlinux.org/elogind.8) listens for, and processes, +ACPI events related to lid-switch activation and the *power*, *suspend* and +*hibernate* keys. This will conflict with the `acpid` service if it is installed +and enabled. Either disable `acpid` when enabling `elogind`, or configure +`elogind` to `ignore` ACPI events in +[logind.conf(5)](https://man.voidlinux.org/logind.conf.5). There are several +configuration options, all starting with the keyword `Handle`, that should be +set to `ignore` to avoid interfering with `acpid`. + +## Power Saving - tlp + +Laptop battery life can be extended by using +[tlp(8)](https://man.voidlinux.org/tlp.8). To use it, install the `tlp` package, +and [enable](./services/index.md#enabling-services) the `tlp` service. Refer to +[the TLP documentation](https://linrunner.de/tlp/) for details. diff --git a/src/config/print/index.md b/src/config/print/index.md new file mode 100644 index 0000000..db754d8 --- /dev/null +++ b/src/config/print/index.md @@ -0,0 +1,114 @@ +# Printing + +CUPS (Common Unix Printing System) is the supported mechanism for connecting to +printers on EvolutionOS. + +As prerequisites, install the `cups` package and enable the `cupsd` service. +Wait until the service is marked available. + +## Installing Printing Drivers + +If the printer is being accessed over the network and supports PostScript or +PCL, CUPS alone should be sufficient. However, additional driver packages are +necessary for local printer support. The `cups-filters` package provides driver +support for CUPS. + +Depending on the hardware in question, additional drivers may be necessary. + +Some CUPS drivers contain proprietary or binary-only extensions. These are +available only in the nonfree repository, and sometimes only for specific +architectures. + +### Driverless printing + +Most modern network printers support printing driverlessly using the IPP +Everywhere standard. See for a list of +self-certified printers supporting this standard. Even if a printer is not on +this list, there is still a high chance it is supported. + +Do note that `cups-filters` is still required for driverless printing. + +### Gutenprint drivers + +Gutenprint provides support for many printers. These drivers are contained in +the `gutenprint` package. + +### HP drivers + +Printers from Hewlett-Packard require the `hplip` package. + +Running the following command will guide you through the driver installation +process. The default configuration selections it suggests are typically +sufficient. + +``` +# hp-setup -i +``` + +### Brother drivers + +For Brother printer support, install the foomatic drivers, which are contained +in the `foomatic-db` and `foomatic-db-nonfree` packages. Support for various +laser models is provided by the `brother-brlaser` package. + +### Drivers for Epson Inkjet printers + +Install the `epson-inkjet-printer-escpr` package for Epson Inkjet printers. + +### Canon PIXMA/MAXIFY drivers + +The `cnijfilter2` package contains drivers for various Canon PIXMA and MAXIFY +models. Please note that installing the driver package requires [enabling the +"nonfree" repository](../../xbps/repositories/index.md#nonfree). + +## Configuring a New Printer + +CUPS provides a web interface and command line tools that can be used to +configure printers. Additionally, various native GUI options are available and +may be better suited, depending on the use-case. + +### Automatically + +Printers with support for IPP Everywhere can be discovered and configured +automatically using [ZeroConf](http://www.zeroconf.org/). To enable this, +install the `avahi` and `nss-mdns` package and enable the `avahi-daemon` +service. + +### Web interface + +To configure the printer using the CUPS web interface, navigate to + in a browser. Under the "Administration" tab, select +"Printers > Add Printer". When asked to log in, use an account that is in the +`lpadmin` group. + +### Command line + +The [lpadmin(8)](https://man.voidlinux.org/lpadmin.8) tool may be used to +configure a printer using the command line. + +### Graphical interface + +The `system-config-printer` package offers simple and robust configuration of +new printers. Install and invoke it: + +``` +# system-config-printer +``` + +Normally this tool requires root privileges. However, if you are using +PolicyKit, you can install the `cups-pk-helper` package to allow unprivileged +users to use `system-config-printer`. + +While `system-config-printer` is shown here, your desktop environment may have a +native printer dialog, which may be found by consulting the documentation for +your DE. + +## Troubleshooting + +### USB printer not shown + +The device URI can be found manually by running: + +``` +# /usr/lib/cups/backend/usb +``` diff --git a/src/config/rc-files.md b/src/config/rc-files.md new file mode 100644 index 0000000..bf2ff7f --- /dev/null +++ b/src/config/rc-files.md @@ -0,0 +1,53 @@ +# rc.conf, rc.local and rc.shutdown + +The files `/etc/rc.conf`, `/etc/rc.local` and `/etc/rc.shutdown` can be used to +configure certain parts of your EvolutionOS system. `rc.conf` is often configured by +`evolution-installer`. + +## rc.conf + +Sourced in runit stages 1 and 3. This file can be used to set variables, +including the following: + +### KEYMAP + +Specifies which keymap to use for the Linux console. Available keymaps are +listed in `/usr/share/kbd/keymaps`. For example: + +``` +KEYMAP=fr +``` + +For further details, refer to +[loadkeys(1)](https://man.voidlinux.org/loadkeys.1). + +### HARDWARECLOCK + +Specifies whether the hardware clock is set to UTC or local time. + +By default this is set to `utc`. However, Windows sets the hardware clock to +local time, so if you are dual-booting with Windows, you need to either +configure Windows to use UTC, or set this variable to `localtime`. + +For further details, refer to [hwclock(8)](https://man.voidlinux.org/hwclock.8). + +### FONT + +Specifies which font to use for the Linux console. Available fonts are listed in +`/usr/share/kbd/consolefonts`. For example: + +``` +FONT=eurlatgr +``` + +For further details, refer to [setfont(8)](https://man.voidlinux.org/setfont.8). + +## rc.local + +Sourced in runit stage 2. A shell script which can be used to specify +configuration to be done prior to login. + +## rc.shutdown + +Sourced in runit stage 3. A shell script which can be used to specify tasks to +be done during shutdown. diff --git a/src/config/security/apparmor.md b/src/config/security/apparmor.md new file mode 100644 index 0000000..519d5a8 --- /dev/null +++ b/src/config/security/apparmor.md @@ -0,0 +1,25 @@ +# AppArmor + +AppArmor is a mandatory access control mechanism (like SELinux). It can +constrain programs based on pre-defined or generated policy definitions. + +EvolutionOS ships with some default profiles for several services, such as `dhcpcd` and +`wpa_supplicant`. Container runtimes such as LXC and podman integrate with +AppArmor for better security for container payloads. + +To use AppArmor on a system, one must: + +1. Install the `apparmor` package. +2. Set `apparmor=1 security=apparmor` on the kernel commandline. + +To accomplish the second step, consult [the documentation on how to modify the +kernel cmdline](./../kernel.md#cmdline). + +The `APPARMOR` variable in `/etc/default/apparmor` controls how profiles will be +loaded at boot, the value is set to `complain` by default and corresponds to +AppArmor modes (`disable`, `complain`, `enforce`). + +AppArmor tools [aa-genprof(8)](https://man.voidlinux.org/aa-genprof.8) and +[aa-logprof(8)](https://man.voidlinux.org/aa-logprof.8) require either +configured [syslog](../services/logging.md) or a running +[auditd(8)](https://man.voidlinux.org/auditd.8) service. diff --git a/src/config/security/index.md b/src/config/security/index.md new file mode 100644 index 0000000..ec13555 --- /dev/null +++ b/src/config/security/index.md @@ -0,0 +1,8 @@ +# Security + +There are several ways you can make your installation more secure. This section +explores some of them. + +## Section Contents + +- [AppArmor](./apparmor.md) diff --git a/src/config/services/index.md b/src/config/services/index.md new file mode 100644 index 0000000..edbe674 --- /dev/null +++ b/src/config/services/index.md @@ -0,0 +1,104 @@ +# Services and Daemons - dinit + +EvolutionOS uses the dinit supervision suite to +run system services and daemons. + +Some advantages of using dinit include: + +- really damn fast, much improved upon the previously used runit +- very simple control panel interface +- drunner, a custom made facility to convert runit services to dinit services + +If you don't need a program to be running constantly, but would like it to run +at regular intervals, you might like to consider using a [cron +daemon](../cron.md). + +## Section Contents + +- [Per-User Services](./user-services.md) +- [Logging](./logging.md) + +## Service Directories + +Each service managed by dinit has an associated *service file*. + +Each service file contains various infomation about how to run the service. + +For more infomation, visit [the manual](https://github.com/davmac314/dinit) + +If a legacy runit service exists, it will be automatically converted on boot + +### Configuring Services + +For service simplicity and user-friendliness, we recommend you configure your services within the program itself + +### Editing Services + +To edit a service, first copy its service file to a different name. +Otherwise, [xbps-install(1)](https://man.voidlinux.org/xbps-install.1) can +overwrite the service file. Then, edit the new service file as needed. +Finally, the old service should be stopped and disabled, and the new one should +be started. + +## Managing Services + +### Basic Usage + +To start, stop, restart or get the status of a service: + +``` +# dinitctl start +# dinitctl stop +# dinitctl restart +# dinitctl status +``` + +#### Enabling Services + +EvolutionOS provides service files for most daemons in `/etc/dinit.d`. + +To enable a service on a system, create a symlink to the service +file in `/etc/dinit.d/boot.d`: + +``` +# ln -s /etc/dinit.d/ /etc/dinit.d/boot.d/ +``` + +You could alternativley use + +``` +# dinitctl enable +``` + +Once a service is linked it will always start on boot and restart if it stops, +unless administratively downed. + +#### Disabling Services + +To disable a service, remove the symlink from the boot.d directory: + +``` +# rm /etc/dinit.d/boot.d/ +``` + +Or, you could simply run + +``` +# dinitctl disable +``` + +#### Testing Services + +To check if a service is working correctly when started by the service +supervisor, run it once before fully enabling it: + +``` +# dinitctl disable +# dinitctl start +``` + +If everything works, run + +``` +# dinitctl enable +``` diff --git a/src/config/services/logging.md b/src/config/services/logging.md new file mode 100644 index 0000000..7802521 --- /dev/null +++ b/src/config/services/logging.md @@ -0,0 +1,12 @@ +# Logging + +## Syslog + +The default installation comes with a syslog daemon, but it is not enabled by +default. To enable it, create a service as documented in this [github page](# dinitctl start ) +for the deamon. The command is called syslogd. + +### Other syslog daemons + +The EvolutionOS repositories also include packages for `rsyslog`, `socklog` and +`metalog`. diff --git a/src/config/services/user-services.md b/src/config/services/user-services.md new file mode 100644 index 0000000..b6378c0 --- /dev/null +++ b/src/config/services/user-services.md @@ -0,0 +1 @@ +# Per-User Services diff --git a/src/config/session-management.md b/src/config/session-management.md new file mode 100644 index 0000000..b5b2af7 --- /dev/null +++ b/src/config/session-management.md @@ -0,0 +1,64 @@ +# Session and Seat Management + +Session and seat management is not necessary for every setup, but it can be used +to safely create temporary runtime directories, provide access to hardware +devices and multi-seat capabilities, and control system shutdown. + +## D-Bus + +D-Bus is an IPC (inter-process communication) mechanism used by userspace +software in Linux. D-Bus can provide a system bus and/or a session bus, the +latter being specific to a user session. + +- To provide a system bus, you should [enable](./services/index.md) the `dbus` + service. This might require a system reboot to work properly. +- To provide a session bus, you can start a given program (usually a window + manager or interactive shell) with + [dbus-run-session(1)](https://man.voidlinux.org/dbus-run-session.1). Most + desktop environments, if launched through an adequate display manager, will + launch a D-Bus session themselves. + +Note that some software assumes the presence of a system bus, while other +software assumes the presence of a session bus. + +## elogind + +[elogind(8)](https://man.voidlinux.org/elogind.8) manages user logins and system +power, as a standalone version of `systemd-logind`. elogind provides necessary +features for most desktop environments and Wayland compositors. It can also be +one of the mechanisms for rootless [Xorg](./graphical-session/xorg.md). + +Please read the "[Power Management](./power-management.md)" section for things +to consider before installing elogind. + +To make use of its features, install the `elogind` package and make sure the +[system D-Bus](#d-bus) is enabled. You might need to log out and in again. + +If you're having any issues with elogind, [enable](./services/index.md) its +service, as waiting for a D-Bus activation can lead to issues. + +## seatd + +[seatd(1)](https://man.voidlinux.org/seatd.1) is a minimal seat management +daemon and an alternative to elogind primarily for [wlroots +compositors](./graphical-session/wayland.md#standalone-compositors). + +To use it, install the `seatd` package and enable its service. If you want +non-root users to be able to access the seatd session, add them to the `_seatd` +group. + +Note that, unlike elogind, seatd doesn't do anything besides managing seats. + +## XDG_RUNTIME_DIR + +`XDG_RUNTIME_DIR` is an environment variable defined by the [XDG Base Directory +Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). +Its value sets the path to the base directory where programs should store +user-specific runtime files. + +Install [elogind](#elogind) as your session manager to automatically set up +`XDG_RUNTIME_DIR`. + +Alternatively, manually set the environment variable through the shell. Make +sure to create a dedicated user directory and set its permissions to `700`. A +good default location is `/run/user/$(id -u)`. diff --git a/src/config/ssd.md b/src/config/ssd.md new file mode 100644 index 0000000..f6b5742 --- /dev/null +++ b/src/config/ssd.md @@ -0,0 +1,147 @@ +# Solid State Drives + +Post installation, you will need to enable TRIM for solid state drives. You can +check which devices allow TRIM by running: + +``` +$ lsblk --discard +``` + +If the DISC-GRAN (discard granularity) and DISC-MAX (discard maximum bytes) +columns are non-zero, that means the block device has TRIM support. If your +solid state drive partition does not show TRIM support, please verify that you +chose a file system with TRIM support (ext4, Btrfs, F2FS, etc.). Note that F2FS +requires kernel 4.19 or above to support TRIM. + +To run TRIM one-shot, you can run +[`fstrim(8)`](https://man.voidlinux.org/fstrim.8) manually. For example, if your +/ directory is on an SSD: + +``` +# fstrim / +``` + +To automate running TRIM, use cron or add the `discard` option to `/etc/fstab`. + +## Periodic TRIM with cron + +Add the following lines to `/etc/cron.weekly/fstrim`: + +``` +#!/bin/sh + +fstrim / +``` + +Finally, make the script executable: + +``` +# chmod u+x /etc/cron.weekly/fstrim +``` + +## Continuous TRIM with fstab discard + +You can use either continuous or periodic TRIM, but usage of continuous TRIM is +discouraged if you have an SSD that doesn't handle NCQ correctly. Refer to the +kernel +[blacklist](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/ata/libata-core.c?h=v5.8&id=bcf876870b95592b52519ed4aafcf9d95999bc9c#n3774). + +Edit `/etc/fstab` and add the `discard` option to block devices that need TRIM. + +For example, if `/dev/sda1` was an SSD partition, formatted as ext4, and mounted +at `/`: + +``` +/dev/sda1 / ext4 defaults,discard 0 1 +``` + +## LVM + +To enable TRIM for LVM's commands (`lvremove`, `lvreduce`, etc.), open +`/etc/lvm/lvm.conf`, uncomment the `issue_discards` option, and set it to `1`: + +``` +issue_discards=1 +``` + +## LUKS + +**Warning**: Before enabling discard for your LUKS partition, please be aware of +the [security +implications](https://wiki.archlinux.org/index.php/Dm-crypt/Specialties#Discard/TRIM_support_for_solid_state_drives_(SSD)). + +To open an encrypted LUKS device and allow discards to pass through, open the +device with the `--allow-discards` option: + +``` +# cryptsetup luksOpen --allow-discards /dev/sdaX luks +``` + +### Non-root devices + +Edit `/etc/crypttab` and set the `discard` option for devices on the SSD. For +example, if you have a LUKS device with the name `externaldrive1`, device +`/dev/sdb2`, and password `none`: + +``` +externaldrive1 /dev/sdb2 none luks,discard +``` + +### Root devices + +If your root device is on LUKS, add `rd.luks.allow-discards` to +`CMDLINE_LINUX_DEFAULT`. In the case of GRUB, edit `/etc/default/grub`: + +``` +GRUB_CMDLINE_LINUX_DEFAULT="rd.luks.allow-discards" +``` + +### Verifying configuration + +To verify that you have configured TRIM correctly for LUKS, run: + +``` +# dmsetup table /dev/mapper/crypt_dev --showkeys +``` + +If this command output contains the string `allow_discards`, you have +successfully enabled TRIM on your LUKS device. + +## ZFS + +Before running `trim` on a ZFS pool, ensure that all devices in the pool support +it: + +``` +# zpool get all | grep trim +``` + +If the pool allows `autotrim` (set `off` by default), you can `trim` the pool +periodically or automatically. To one-shot `trim` `yourpoolname`: + +``` +# zpool trim yourpoolname +``` + +### Periodic TRIM + +Add the following lines to `/etc/cron.daily/ztrim`: + +``` +#!/bin/sh +zpool trim yourpoolname +``` + +Finally, make the script executable: + +``` +# chmod u+x /etc/cron.daily/ztrim +``` + +### Autotrim + +To set autotrim for `yourpoolname`, run: + +``` +# zpool set autotrim=on yourpoolname +``` diff --git a/src/config/texlive.md b/src/config/texlive.md new file mode 100644 index 0000000..8e26a27 --- /dev/null +++ b/src/config/texlive.md @@ -0,0 +1,98 @@ +# TeX Live + +In EvolutionOS, the `texlive-bin` package provides a basic TeX installation, including +the `tlmgr` program. Use `tlmgr` to install TeX packages and package collections +from CTAN mirrors. Install the `gnupg` package to allow `tlmgr` to verify TeX +packages. + +The `texlive-bin` package contains the latest TeX Live version; however, earlier +versions, such as `texlive2018-bin`, are also available. + +The `texlive` package and `texlive-*` packages are also available, and provide +TeX packages directly via xbps. TeX packages installed via those packages cannot +interact with TeX packages installed directly from CTAN (via `tlmgr`). For +example: `pdflatex` from `texlive-pdflatex` cannot be used to compile a TeX +document that uses a package installed via `tlmgr`; `tlmgr install pdflatex` +would be required for that. + +## Configuring TeX Live + +After installing TeX Live, update the value of `PATH`: + +``` +$ source /etc/profile +``` + +Check that `/opt/texlive//bin/x86_64-linux` (or +`/opt/texlive//bin/i386-linux`) is in your `PATH`: + +``` +$ echo $PATH +``` + +If required, change the global default paper size: + +``` +# tlmgr paper +``` + +## Installing/Updating TeX packages + +To install all available packages: + +``` +# tlmgr install scheme-full +``` + +To install specific packages, you can install the collection(s) including them. +To list the available collections: + +``` +$ tlmgr info collections +``` + +To see the list of files owned by a collection: + +``` +$ tlmgr info --list collection- +``` + +To install the collection: + +``` +# tlmgr install collection- +``` + +To install a standalone package, first check if the package exists: + +``` +$ tlmgr search --global +``` + +and then install it: + +``` +# tlmgr install +``` + +To find the package providing a particular file (for example, a font): + +``` +$ tlmgr search --file --global +``` + +To remove a package or a collection: + +``` +# tlmgr remove +``` + +To update installed packages: + +``` +# tlmgr update --all +``` + +For a full description, check: + + diff --git a/src/config/users-and-groups.md b/src/config/users-and-groups.md new file mode 100644 index 0000000..5faa169 --- /dev/null +++ b/src/config/users-and-groups.md @@ -0,0 +1,84 @@ +# Users and Groups + +The [useradd(8)](https://man.voidlinux.org/useradd.8), +[userdel(8)](https://man.voidlinux.org/userdel.8) and +[usermod(8)](https://man.voidlinux.org/usermod.8) commands are used to add, +delete and modify users respectively. The +[passwd(1)](https://man.voidlinux.org/passwd.1) command is used to change +passwords. + +The [groupadd(8)](https://man.voidlinux.org/groupadd.8), +[groupdel(8)](https://man.voidlinux.org/groupdel.8) and +[groupmod(8)](https://man.voidlinux.org/groupmod.8) commands are used to add, +delete and modify groups respectively. The +[groups(1)](https://man.voidlinux.org/groups.1) command lists all groups a user +belongs to. + +## Default shell + +The default shell for a user can be changed with +[chsh(1)](https://man.voidlinux.org/chsh.1): + +``` +$ chsh -s +``` + +`` must be the path to the shell as specified by `/etc/shells` or the +output of `chsh -l`, which provides a list of installed shells. + +## sudo + +[sudo(8)](https://man.voidlinux.org/sudo.8) is installed by default, but might +not be configured appropriately for your needs. It is only necessary to +configure sudo if you wish to use it. + +Use [visudo(8)](https://man.voidlinux.org/visudo.8) as root to edit the +[sudoers(5)](https://man.voidlinux.org/sudoers.5) file. + +To create a superuser, uncomment the line + +``` +#%wheel ALL=(ALL) ALL +``` + +and add users to the `wheel` group. + +## Default Groups + +EvolutionOS defines a number of groups by default. + +| Group | Description | +|------------|---------------------------------------------------------------| +| `root` | Complete access to the system. | +| `bin` | Unused - present for historical reasons. | +| `sys` | Unused - present for historical reasons. | +| `kmem` | Ability to read from `/dev/mem` and `/dev/port`. | +| `wheel` | Elevated privileges for specific system administration tasks. | +| `tty` | Access to TTY-like devices: | +| | `/dev/tty*`, `/dev/pts*`, `/dev/vcs*`. | +| `tape` | Access to tape devices. | +| `daemon` | System daemons that need to write to files on disk. | +| `floppy` | Access to floppy drives. | +| `disk` | Raw access to `/dev/sd*` and `/dev/loop*`. | +| `lp` | Access to printers. | +| `dialout` | Access to serial ports. | +| `audio` | Access to audio devices. | +| `video` | Access to video devices. | +| `utmp` | Ability to write to `/var/run/utmp`, `/var/log/wtmp` | +| | and `/var/log/btmp`. | +| `adm` | Unused - present for historical reasons. This group was | +| | traditionally used for system monitoring, such as viewing | +| | files in `/var/log`. | +| `cdrom` | Access to CD devices. | +| `optical` | Access to DVD/CD-RW devices. | +| `mail` | Used by some mail packages, e.g. `dma`. | +| `storage` | Access to removable storage devices. | +| `scanner` | Ability to access scanners. | +| `network` | Unused - present for historical reasons. | +| `kvm` | Ability to use KVM for virtual machines, e.g. via QEMU. | +| `input` | Access to input devices: `/dev/mouse*`, `/dev/event*`. | +| `plugdev` | Access to pluggable devices. | +| `nogroup` | System daemons that don't need to own any files. | +| `usbmon` | Access to `/dev/usbmon*`. | +| `users` | Ordinary users. | +| `xbuilder` | To use xbps-uchroot(1) with `xbps-src`. | diff --git a/src/contributing/evolution-docs/index.md b/src/contributing/evolution-docs/index.md new file mode 100644 index 0000000..f70e589 --- /dev/null +++ b/src/contributing/evolution-docs/index.md @@ -0,0 +1,10 @@ +# Contributing To evolution-docs + +The sources for this handbook are hosted in the +[evolution-docs](https://github.com/evolution-linux/evolution-docs) repository on +[GitHub](https://github.com). If you would like to make a contribution, please +read about [the purpose of the Handbook](../../about/about-this-handbook.md), +follow our [style +guide](https://github.com/evolution-linux/evolution-docs/blob/master/CONTRIBUTING.md#style-guide) +and [submit a pull +request](https://github.com/evolution-linux/evolution-docs/blob/master/CONTRIBUTING.md#submitting-changes). diff --git a/src/contributing/index.md b/src/contributing/index.md new file mode 100644 index 0000000..8cc3d31 --- /dev/null +++ b/src/contributing/index.md @@ -0,0 +1,35 @@ +# Contributing + +There's more to running a distribution than just writing code. + +To contribute to the EvolutionOS packages repository, start by reading the +[CONTRIBUTING](https://github.com/evolution-linux/evolution-packages/blob/master/CONTRIBUTING.md) +document in the evolution-packages GitHub repository. + +To contribute to this Handbook, read +[CONTRIBUTING](https://github.com/evolution-linux/evolution-docs/blob/master/CONTRIBUTING.md) +in the evolution-docs repository. + +If you have any questions, feel free to email Tracker-Friendly at jliwin98@danwin1210.de + +## Usage Statistics + +If you would like to contribute usage reports, the +[PopCorn](https://github.com/the-maldridge/popcorn) program reports installation +statistics back to the Void project. These statistics are purely opt-in - +PopCorn is *not* installed or enabled by default on any Void or EvolutionOS systems. +Additionally, PopCorn requires that port 8001 not be blocked on your system. + +*PopCorn* only reports which packages are installed, their version, and the host +CPU architecture (the output of `xuname`). This does not report which services +are enabled, or any other personal information. Individual systems are tracked +persistently by a random (client-generated) UUID, to ensure that each system is +only counted once in each 24-hour sampling period. + +The data collected by *PopCorn* is available to view at + + +### Setting up PopCorn + +First, install the `PopCorn` package. Then, enable the `popcorn` service, which +will attempt to report statistics once per day. diff --git a/src/installation/guides/arm-devices/index.md b/src/installation/guides/arm-devices/index.md new file mode 100644 index 0000000..35e1815 --- /dev/null +++ b/src/installation/guides/arm-devices/index.md @@ -0,0 +1,3 @@ +# ARM Devices + +ARM is not supported currently. A future update may add ARM support. diff --git a/src/installation/guides/arm-devices/platforms.md b/src/installation/guides/arm-devices/platforms.md new file mode 100644 index 0000000..2ca80ee --- /dev/null +++ b/src/installation/guides/arm-devices/platforms.md @@ -0,0 +1,3 @@ +# Supported Platforms + +ARM Is not currently supported. diff --git a/src/installation/guides/chroot.md b/src/installation/guides/chroot.md new file mode 100644 index 0000000..41748cc --- /dev/null +++ b/src/installation/guides/chroot.md @@ -0,0 +1,288 @@ +# Installation via chroot (x86/x86_64/aarch64) + +This guide details the process of manually installing EvolutionOS via a chroot on an +x86, x86_64 or aarch64 architecture. It is assumed that you have a familiarity +with Linux, but not necessarily with installing a Linux system via a chroot. +This guide can be used to create a "typical" setup, using a single partition on +a single SATA/IDE/USB disk. Each step may be modified to create less typical +setups, such as [full disk encryption](./fde.md). + +EvolutionOS provides two options for bootstrapping the new installation. The **XBPS +method** uses the [XBPS Package Manager](../../xbps/index.md) running on a host +operating system to install the base system. The **ROOTFS method** installs the +base system by unpacking a ROOTFS tarball. + +The **XBPS method** requires that the host operating system have XBPS installed. +This may be an existing installation of EvolutionOS, an official [live +image](../live-images/prep.md), or any Linux installation running a [statically +linked XBPS](../../xbps/troubleshooting/static.md). + +## Prepare Filesystems + +[Partition your disks](../live-images/partitions.md) and format them using +[mke2fs(8)](https://man.voidlinux.org/mke2fs.8), +[mkfs.xfs(8)](https://man.voidlinux.org/mkfs.xfs.8), +[mkfs.btrfs(8)](https://man.voidlinux.org/mkfs.btrfs.8) or whatever tools are +necessary for your filesystem(s) of choice. + +[mkfs.vfat(8)](https://man.voidlinux.org/mkfs.vfat.8) is also available to +create FAT32 partitions. However, due to restrictions associated with FAT +filesystems, it should only be used when no other filesystem is suitable (such +as for the EFI System Partition). + +[cfdisk(8)](https://man.voidlinux.org/cfdisk.8) and +[fdisk(8)](https://man.voidlinux.org/fdisk.8) are available on the live images +for partitioning, but you may wish to use +[gdisk(8)](https://man.voidlinux.org/gdisk.8) (from the package `gptfdisk`) or +[parted(8)](https://man.voidlinux.org/parted.8) instead. + +For a UEFI booting system, make sure to create an EFI System Partition (ESP). +The ESP should have the partition type "EFI System" (code `EF00`) and be +formatted as FAT32 using [mkfs.vfat(8)](https://man.voidlinux.org/mkfs.vfat.8). + +If you're unsure what partitions to create, create a 1GB partition of type "EFI +System" (code `EF00`), then create a second partition of type "Linux Filesystem" +(code `8300`) using the remainder of the drive. + +Format these partitions as FAT32 and ext4, respectively: + +``` +# mkfs.vfat /dev/sda1 +# mkfs.ext4 /dev/sda2 +``` + +### Create a New Root and Mount Filesystems + +This guide will assume the new root filesystem is mounted on `/mnt`. You may +wish to mount it elsewhere. + +If using UEFI, mount the EFI System Partition as `/mnt/boot/efi`. + +For example, if `/dev/sda2` is to be mounted as `/` and `dev/sda1` is the EFI +System Partition: + +``` +# mount /dev/sda2 /mnt/ +# mkdir -p /mnt/boot/efi/ +# mount /dev/sda1 /mnt/boot/efi/ +``` + +Initialize swap space, if desired, using +[mkswap(8)](https://man.voidlinux.org/mkswap.8). + +## Base Installation + +Follow only one of the two following subsections. + +If on aarch64, it will be necessary to install a kernel package in addition to +`base-system`. For example, `linux` is a kernel package that points to the +latest stable kernel packaged by EvolutionOS. + +### The XBPS Method + +Select a [mirror](../../xbps/repositories/mirrors/index.md) and **use the** +[**appropriate URL**](../../xbps/repositories/index.md#the-main-repository) for +the type of system you wish to install. For simplicity, save this URL to a shell +variable. A glibc installation, for example, would use: + +``` +# REPO=https://evolution-linux.github.io/pkg +# REPO=https://repo-default.voidlinux.org/current +``` + +XBPS also needs to know what architecture is being installed. Available options +are `x86_64`, `x86_64-musl`, `i686` for PC architecture computers and `aarch64`. +For example: + +``` +# ARCH=x86_64 +``` + +This architecture must be compatible with your current operating system, but +does not need to be the same. If your host is running an x86_64 operating +system, any of the three architectures can be installed (whether the host is +musl or glibc), but an i686 host can only install i686 distributions. + +Copy the RSA keys from the installation medium to the target root directory: + +``` +# mkdir -p /mnt/var/db/xbps/keys +# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/ +``` + +Use [xbps-install(1)](https://man.voidlinux.org/xbps-install.1) to bootstrap the +installation by installing the `base-system` metapackage: + +``` +# XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" base-system +``` + +## Configuration + +With the exception of the section "Install base-system (ROOTFS method only)", +the remainder of this guide is common to both the XBPS and ROOTFS installation +methods. + +### Entering the Chroot + +[xchroot(1)](https://man.voidlinux.org/xchroot.1) (from `xtools`) can be used to +set up and enter the chroot. Alternatively, this can be [done +manually](../../config/containers-and-vms/chroot.md#manual-method). + +``` +# xchroot /mnt /bin/bash +``` +### Installation Configuration + +Specify the hostname in `/etc/hostname`. Go through the options in +[`/etc/rc.conf`](../../config/rc-files.md#rcconf). If installing a glibc +distribution, edit `/etc/default/libc-locales`, uncommenting desired +[locales](../../config/locales.md). + +[nvi(1)](https://man.voidlinux.org/nvi.1) is available in the chroot, but you +may wish to install your preferred text editor at this time. + +For glibc builds, generate locale files with: + +``` +[xchroot /mnt] # xbps-reconfigure -f glibc-locales +``` + +### Set a Root Password + +[Configure at least one super user account](../../config/users-and-groups.md). +Other user accounts can be configured later, but there should either be a root +password, or a new user account with [sudo(8)](https://man.voidlinux.org/sudo.8) +privileges. + +To set a root password, run: + +``` +[xchroot /mnt] # passwd +``` + +### Configure fstab + +The [fstab(5)](https://man.voidlinux.org/fstab.5) file can be automatically +generated from currently mounted filesystems by copying the file `/proc/mounts`: + +``` +[xchroot /mnt] # cp /proc/mounts /etc/fstab +``` + +Remove lines in `/etc/fstab` that refer to `proc`, `sys`, `devtmpfs` and `pts`. + +Replace references to `/dev/sdXX`, `/dev/nvmeXnYpZ`, etc. with their respective +UUID, which can be found by running +[blkid(8)](https://man.voidlinux.org/blkid.8). Referring to filesystems by their +UUID guarantees they will be found even if they are assigned a different name at +a later time. In some situations, such as booting from USB, this is absolutely +essential. In other situations, disks will always have the same name unless +drives are physically added or removed. Therefore, this step may not be strictly +necessary, but is almost always recommended. + +Change the last zero of the entry for `/` to `1`, and the last zero of every +other line to `2`. These values configure the behaviour of +[fsck(8)](https://man.voidlinux.org/fsck.8). + +For example, the partition scheme used throughout previous examples yields the +following `fstab`: + +``` +/dev/sda1 /boot/efi vfat rw,relatime,[...] 0 0 +/dev/sda2 / ext4 rw,relatime 0 0 +``` + +The information from `blkid` results in the following `/etc/fstab`: + +``` +UUID=6914[...] /boot/efi vfat rw,relatime,[...] 0 2 +UUID=dc1b[...] / ext4 rw,relatime 0 1 +``` + +Note: The output of `/proc/mounts` will have a single space between each field. +The columns are aligned here for readability. + +Add an entry to mount `/tmp` in RAM: + +``` +tmpfs /tmp tmpfs defaults,nosuid,nodev 0 0 +``` + +If using swap space, add an entry for any swap partitions: + +``` +UUID=1cb4[...] swap swap rw,noatime,discard 0 0 +``` + +## Installing GRUB + +Use +[grub-install](https://www.gnu.org/software/grub/manual/grub/html_node/Installing-GRUB-using-grub_002dinstall.html) +to install GRUB onto your boot disk. + +**On a BIOS computer**, install the package `grub`, then run `grub-install +/dev/sdX`, where `/dev/sdX` is the drive (not partition) that you wish to +install GRUB to. For example: + +``` +[xchroot /mnt] # xbps-install grub +[xchroot /mnt] # grub-install /dev/sda +``` + +**On a UEFI computer**, install either `grub-x86_64-efi`, `grub-i386-efi` or +`grub-arm64-efi`, depending on your architecture, then run `grub-install`, +optionally specifying a bootloader label (this label may be used by your +computer's firmware when manually selecting a boot device): + +``` +[xchroot /mnt] # xbps-install grub-x86_64-efi +[xchroot /mnt] # grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id="Void" +``` + +### Troubleshooting GRUB installation + +If EFI variables are not available, add the option `--no-nvram` to the +`grub-install` command. + +#### Installing on removable media or non-compliant UEFI systems + +Unfortunately, not all systems have a fully standards compliant UEFI +implementation. In some cases, it is necessary to "trick" the firmware into +booting by using the default fallback location for the bootloader instead of a +custom one. In that case, or if installing onto a removable disk (such as USB), +add the option `--removable` to the `grub-install` command. + +Alternatively, use [mkdir(1)](https://man.voidlinux.org/mkdir.1) to create the +`/boot/efi/EFI/boot` directory and copy the installed GRUB executable, usually +located in `/boot/efi/EFI/Void/grubx64.efi` (its location can be found using +[efibootmgr(8)](https://man.voidlinux.org/efibootmgr.8)), into the new folder: + +``` +[xchroot /mnt] # mkdir -p /boot/efi/EFI/boot +[xchroot /mnt] # cp /boot/efi/EFI/Void/grubx64.efi /boot/efi/EFI/boot/bootx64.efi +``` + +## Finalization + +Use [xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) to +ensure all installed packages are configured properly: + +``` +[xchroot /mnt] # xbps-reconfigure -fa +``` + +This will make [dracut(8)](https://man.voidlinux.org/dracut.8) generate an +initramfs, and will make GRUB generate a working configuration. + +At this point, the installation is complete. Exit the chroot and reboot your +computer: + +``` +[xchroot /mnt] # exit +# umount -R /mnt +# shutdown -r now +``` + +After booting into your evolutionOS installation for the first time, [perform a system +update](../../xbps/index.md#updating). diff --git a/src/installation/guides/fde.md b/src/installation/guides/fde.md new file mode 100644 index 0000000..eff0c01 --- /dev/null +++ b/src/installation/guides/fde.md @@ -0,0 +1,289 @@ +# Full Disk Encryption + +**Warning**: Your drive's block device and other information may be different, +so make sure it is correct. + +## Partitioning + +Boot a live image and login. + +Create a single physical partition on the disk using +[cfdisk](https://man.voidlinux.org/cfdisk), marking it as bootable. For an MBR +system, the partition layout should look like the following. + +``` +# fdisk -l /dev/sda +Disk /dev/sda: 48 GiB, 51539607552 bytes, 100663296 sectors +Units: sectors of 1 * 512 = 512 bytes +Sector size (logical/physical): 512 bytes / 512 bytes +I/O size (minimum/optimal): 512 bytes / 512 bytes +Disklabel type: dos +Disk identifier: 0x4d532059 + +Device Boot Start End Sectors Size Id Type +/dev/sda1 * 2048 100663295 100661248 48G 83 Linux +``` + +UEFI systems will need the disk to have a GPT disklabel and an EFI system +partition. The required size for this may vary depending on needs, but 100M +should be enough for most cases. For an EFI system, the partition layout should +look like the following. + +``` +# fdisk -l /dev/sda +Disk /dev/sda: 48 GiB, 51539607552 bytes, 100663296 sectors +Units: sectors of 1 * 512 = 512 bytes +Sector size (logical/physical): 512 bytes / 512 bytes +I/O size (minimum/optimal): 512 bytes / 512 bytes +Disklabel type: gpt +Disk identifier: EE4F2A1A-8E7F-48CA-B3D0-BD7A01F6D8A0 + +Device Start End Sectors Size Type +/dev/sda1 2048 264191 262144 128M EFI System +/dev/sda2 264192 100663262 100399071 47.9G Linux filesystem +``` + +## Encrypted volume configuration + +[Cryptsetup](https://man.voidlinux.org/cryptsetup.8) defaults to LUKS2, yet GRUB +releases before 2.06 only had support for LUKS1. + +LUKS2 is only partially supported by GRUB; specifically, only the PBKDF2 key +derivation function is +[implemented](https://git.savannah.gnu.org/cgit/grub.git/commit/?id=365e0cc3e7e44151c14dd29514c2f870b49f9755), +which is *not* the default KDF used with LUKS2, that being Argon2i ([GRUB Bug +59409](https://savannah.gnu.org/bugs/?59409)). LUKS encrypted partitions using +Argon2i (as well as the other KDF) can *not* be decrypted. For that reason, this +guide only recommends LUKS1 be used. + +Keep in mind the encrypted volume will be `/dev/sda2` on EFI systems, since +`/dev/sda1` is taken up by the EFI partition. + +``` +# cryptsetup luksFormat --type luks1 /dev/sda1 + +WARNING! +======== +This will overwrite data on /dev/sda1 irrevocably. + +Are you sure? (Type uppercase yes): YES +Enter passphrase: +Verify passphrase: +``` + +Once the volume is created, it needs to be opened. Replace `voidvm` with an +appropriate name. Again, this will be `/dev/sda2` on EFI systems. + +``` +# cryptsetup luksOpen /dev/sda1 voidvm +Enter passphrase for /dev/sda1: +``` + +Once the LUKS container is opened, create the LVM volume group using that +partition. + +``` +# vgcreate voidvm /dev/mapper/voidvm + Volume group "voidvm" successfully created +``` + +There should now be an empty volume group named `voidvm`. + +Next, logical volumes need to be created for the volume group. For this example, +I chose 10G for `/`, 2G for `swap`, and will assign the rest to `/home`. + +``` +# lvcreate --name root -L 10G voidvm + Logical volume "root" created. +# lvcreate --name swap -L 2G voidvm + Logical volume "swap" created. +# lvcreate --name home -l 100%FREE voidvm + Logical volume "home" created. +``` + +Next, create the filesystems. The example below uses XFS as a personal +preference of the author. Any filesystem [supported by +GRUB](https://www.gnu.org/software/grub/manual/grub/grub.html#Features) will +work. + +``` +# mkfs.xfs -L root /dev/voidvm/root +meta-data=/dev/voidvm/root isize=512 agcount=4, agsize=655360 blks +... +# mkfs.xfs -L home /dev/voidvm/home +meta-data=/dev/voidvm/home isize=512 agcount=4, agsize=2359040 blks +... +# mkswap /dev/voidvm/swap +Setting up swapspace version 1, size = 2 GiB (2147479552 bytes) +``` + +## System installation + +Next, setup the chroot and install the base system. + +``` +# mount /dev/voidvm/root /mnt +# mkdir -p /mnt/home +# mount /dev/voidvm/home /mnt/home +``` + +On a UEFI system, the EFI system partition also needs to be mounted. + +``` +# mkfs.vfat /dev/sda1 +# mkdir -p /mnt/boot/efi +# mount /dev/sda1 /mnt/boot/efi +``` + +Copy the RSA keys from the installation medium to the target root directory: + +``` +# mkdir -p /mnt/var/db/xbps/keys +# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/ +``` + +Before we enter the chroot to finish up configuration, we do the actual install. +Do not forget to use the [appropriate repository +URL](../../xbps/repositories/index.md#the-main-repository) for the type of +system you wish to install. + +``` +# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system lvm2 cryptsetup grub +[*] Updating `https://repo-default.voidlinux.org/current/x86_64-repodata' ... +x86_64-repodata: 1661KB [avg rate: 2257KB/s] +130 packages will be downloaded: +... +``` + +UEFI systems will have a slightly different package selection. The installation +command for a UEFI system will be as follows. + +``` +# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system cryptsetup grub-x86_64-efi lvm2 +``` + +When it's done, we can enter the chroot with +[`xchroot(1)`](https://man.voidlinux.org/xchroot.1) (from `xtools`) and finish +up the configuration. Alternatively, entering the chroot can be [done +manually](../../config/containers-and-vms/chroot.md#manual-method). + +``` +# xchroot /mnt +[xchroot /mnt] # chown root:root / +[xchroot /mnt] # chmod 755 / +[xchroot /mnt] # passwd root +[xchroot /mnt] # echo voidvm > /etc/hostname +``` + +and, for glibc systems only: + +``` +[xchroot /mnt] # echo "LANG=en_US.UTF-8" > /etc/locale.conf +[xchroot /mnt] # echo "en_US.UTF-8 UTF-8" >> /etc/default/libc-locales +[xchroot /mnt] # xbps-reconfigure -f glibc-locales +``` + +### Filesystem configuration + +The next step is editing `/etc/fstab`, which will depend on how you configured +and named your filesystems. For this example, the file should look like this: + +``` +# +tmpfs /tmp tmpfs defaults,nosuid,nodev 0 0 +/dev/voidvm/root / xfs defaults 0 0 +/dev/voidvm/home /home xfs defaults 0 0 +/dev/voidvm/swap swap swap defaults 0 0 +``` + +UEFI systems will also have an entry for the EFI system partition. + +``` +/dev/sda1 /boot/efi vfat defaults 0 0 +``` + +### GRUB configuration + +Next, configure GRUB to be able to unlock the filesystem. Add the following line +to `/etc/default/grub`: + +``` +GRUB_ENABLE_CRYPTODISK=y +``` + +Next, the kernel needs to be configured to find the encrypted device. First, +find the UUID of the device. + +``` +[xchroot /mnt] # blkid -o value -s UUID /dev/sda1 +135f3c06-26a0-437f-a05e-287b036440a4 +``` + +Edit the `GRUB_CMDLINE_LINUX_DEFAULT=` line in `/etc/default/grub` and add +`rd.lvm.vg=voidvm rd.luks.uuid=` to it. Make sure the UUID matches the one +for the `sda1` device found in the output of the +[blkid(8)](https://man.voidlinux.org/blkid.8) command above. This will be +`/dev/sda2` on EFI systems. + +## LUKS key setup + +And now to avoid having to enter the password twice on boot, a key will be +configured to automatically unlock the encrypted volume on boot. First, generate +a random key. + +``` +[xchroot /mnt] # dd bs=1 count=64 if=/dev/urandom of=/boot/volume.key +64+0 records in +64+0 records out +64 bytes copied, 0.000662757 s, 96.6 kB/s +``` + +Next, add the key to the encrypted volume. + +``` +[xchroot /mnt] # cryptsetup luksAddKey /dev/sda1 /boot/volume.key +Enter any existing passphrase: +``` + +Change the permissions to protect the generated key. + +``` +[xchroot /mnt] # chmod 000 /boot/volume.key +[xchroot /mnt] # chmod -R g-rwx,o-rwx /boot +``` + +This keyfile also needs to be added to `/etc/crypttab`. Again, this will be +`/dev/sda2` on EFI systems. + +``` +voidvm /dev/sda1 /boot/volume.key luks +``` + +And then the keyfile and `crypttab` need to be included in the initramfs. Create +a new file at `/etc/dracut.conf.d/10-crypt.conf` with the following line: + +``` +install_items+=" /boot/volume.key /etc/crypttab " +``` + +## Complete system installation + +Next, install the boot loader to the disk. + +``` +[xchroot /mnt] # grub-install /dev/sda +``` + +Ensure an initramfs is generated: + +``` +[xchroot /mnt] # xbps-reconfigure -fa +``` + +Exit the `chroot`, unmount the filesystems, and reboot the system. + +``` +[xchroot /mnt] # exit +# umount -R /mnt +# reboot +``` diff --git a/src/installation/guides/index.md b/src/installation/guides/index.md new file mode 100644 index 0000000..9274234 --- /dev/null +++ b/src/installation/guides/index.md @@ -0,0 +1,10 @@ +# Advanced Installation Guides + +This section contains guides for more specific or complex use-cases. + +## Section Contents + +- [Installing evolutionOS via chroot (x86 or x86_64)](./chroot.md) +- [Installing evolutionOS with Full Disk Encryption](./fde.md) +- [Installing evolutionOS on a ZFS Root](./zfs.md) +- [ARM Devices](./arm-devices/index.md) diff --git a/src/installation/guides/zfs.md b/src/installation/guides/zfs.md new file mode 100644 index 0000000..a6bdd5a --- /dev/null +++ b/src/installation/guides/zfs.md @@ -0,0 +1,179 @@ +# Installing EvolutionOS on a ZFS Root + +Because the EvolutionOS installer does not support ZFS, it is necessary to install via +chroot. Aside from a few caveats regarding bootloader and initramfs support, +installing EvolutionOS on a ZFS root filesystem is not significantly different from any +other advanced installation. [ZFSBootMenu](https://zfsbootmenu.org) is a +bootloader designed from the ground up to support booting Linux distributions +directly from a ZFS pool. However, it is also possible to use traditional +bootloaders with a ZFS root. + +## ZFSBootMenu + +ZFSBootMenu supports native ZFS encryption, offers a convenient recovery +environment that can be used to clone prior snapshots or perform advanced +manipulation in a pre-boot environment, and will support booting from any +pool that is importable by modern ZFS drivers. The ZFSBootMenu documentation +offers, among other content, several [step-by-step guides](https://docs.zfsbootmenu.org/en/latest/guides/void-linux.html) for installing a EvolutionOS system from scratch. The [UEFI guide](https://docs.zfsbootmenu.org/en/latest/guides/void-linux/uefi.html) +describes the procedure of bootstrapping a EvolutionOS system for modern systems. For +legacy BIOS systems, the [syslinux guide](https://docs.zfsbootmenu.org/en/latest/guides/void-linux/syslinux-mbr.html)provides comparable instructions. + +## Traditional bootloaders + +For those that wish to forego ZFSBootMenu, it is possible to bootstrap a EvolutionOS +system with another bootloader. To avoid unnecessary complexity, systems that +use bootloaders other than ZFSBootMenu should plan to use a separate `/boot` +that is located on an ext4 or xfs filesystem. + +### Installation media + +Installing EvolutionOS to a ZFS root requires an installation medium with ZFS drivers. +It is possible to build a custom image from the official +[evolution-installer](https://centrifuge.hectabit.org/evolutionos/evolution-installer) repository by providing +the command-line option `-p zfs` to the `mklive.sh` script. However, for +`x86_64` systems, it may be more convenient to fetch a pre-built +[hrmpf](https://github.com/leahneukirchen/hrmpf/releases) image. These images, +maintained by the Void Linux projects, are extensions of the standard Void live +images that include pre-compiled ZFS modules in addition to other useful tools. +To use these, add https://hectabit.org/evolutionos/pkg to the repository list. + +### Partition disks + +After booting a live image with ZFS support, [partition your +disks](../live-images/partitions.md). The considerations in the partitioning +guide apply to ZFS installations as well, except that + +- The boot partition should be considered necessary unless you intend to use + `gummiboot`, which expects that your EFI system partition will be mounted at + `/boot`. (This alternative configuration will not be discussed here.) +- Aside from any EFI system partition, GRUB BIOS boot partition, swap or boot + partitions, the remainder of the disk should typically be a single partition + with type code `BF00` that will be dedicated to a single ZFS pool. There is + no benefit to creating separate ZFS pools on a single disk. + +As needed, format the EFI system partition using +[mkfs.vfat(8)](https://man.voidlinux.org/mkfs.vfat.8) and the the boot partition +using [mke2fs(8)](https://man.voidlinux.org/mke2fs.8) or +[mkfs.xfs(8)](https://man.voidlinux.org/mkfs.xfs.8). Initialize any swap space +using [mkswap(8)](https://man.voidlinux.org). + +> It is possible to put Linux swap space on a ZFS zvol, although there may be a +> risk of deadlocking the kernel when under high memory pressure. This guide +> takes no position on the matter of swap space on a zvol. However, if you wish +> to use suspension-to-disk (hibernation), note that the kernel is not capable +> of resuming from memory images stored on a zvol. You will need a dedicated +> swap partition to use hibernation. Apart from this caveat, there are no +> special considerations required to resume a suspended image when using a ZFS +> root. + +### Create a ZFS pool + +Create a ZFS pool on the partition created for it using +[zpool(8)](https://man.voidlinux.org/zpool.8). For example, to create a pool on +`/dev/disk/by-id/wwn-0x5000c500deadbeef-part3`: + +``` +# zpool create -f -o ashift=12 \ + -O compression=lz4 \ + -O acltype=posixacl \ + -O xattr=sa \ + -O relatime=on \ + -o autotrim=on \ + -m none zroot /dev/disk/by-id/wwn-0x5000c500deadbeef-part3 +``` + +Adjust the pool (`-o`) and filesystem (`-O`) options as desired, and replace the +partition identifier `wwn-0x5000c500deadbeef-part3` with that of the actual +partition to be used. + +> When adding disks or partitions to ZFS pools, it is generally advisable to +> refer to them by the symbolic links created in `/dev/disk/by-id` or (on UEFI +> systems) `/dev/disk/by-partuuid` so that ZFS will identify the right +> partitions even if disk naming should change at some point. Using traditional +> device nodes like `/dev/sda3` may cause intermittent import failures. + +Next, export and re-import the pool with a temporary, alternate root path: + +``` +# zpool export zroot +# zpool import -N -R /mnt zroot +``` + +### Create initial filesystems + +The filesystem layout on your ZFS pool is flexible. However, it is customary to +put operating system root filesystems ("boot environments") under a `ROOT` +parent: + +``` +# zfs create -o mountpoint=none zroot/ROOT +# zfs create -o mountpoint=/ -o canmount=noauto zroot/ROOT/void +``` + +Setting `canmount=noauto` on filesystems with `mountpoint=/` is useful because +it permits the creation of multiple boot environments (which may be clones of a +common Void installation or contain completely separate distributions) without +fear that ZFS auto-mounting will attempt to mount one over another. + +To separate user data from the operating system, create a filesystem to store +home directories: + +``` +# zfs create -o mountpoint=/home zroot/home +``` + +Other filesystems may be created as desired. + +### Mount the ZFS hierarchy + +All ZFS filesystems should be mounted under the `/mnt` alternate root +established by the earlier re-import. Mount the manual-only root filesystem +before allowing ZFS to automatically mount everything else: + +``` +# zfs mount zroot/ROOT/void +# zfs mount -a +``` + +At this point, the entire ZFS hierarchy should be mounted and ready for +installation. To improve boot-time import speed, it is useful to record the +current pool configuration in a cache file that EvolutionOS will use to avoid walking +the entire device hierarchy to identify importable pools: + +``` +# mkdir -p /mnt/etc/zfs +# zpool set cachefile=/mnt/etc/zfs/zpool.cache zroot +``` + +Mount non-ZFS filesystems at the appropriate places. For example, if `/dev/sda2` +holds an ext4 filesystem that should be mounted at `/boot` and `/dev/sda1` is +the EFI system partition: + +``` +# mkdir -p /mnt/boot +# mount /dev/sda2 /mnt/boot +# mkdir -p /mnt/boot/efi +# mount /dev/sda1 /mnnt/boot/efi +``` + +### Installation + +At this point, ordinary installation can proceed from the ["Base Installation" +section](https://docs.voidlinux.org/installation/guides/chroot.html#base-installation). +of the standard chroot installation guide. However, before following the +["Finalization" +instructions](./chroot.html#finalization), +make sure that the `zfs` package has been installed and `dracut` is configured +to identify a ZFS root filesystem: + +``` +[xchroot /mnt] # mkdir -p /etc/dracut.conf.d +[xchroot /mnt] # cat > /etc/dracut.conf.d/zol.conf <. Previous releases +can be found under , organized by +date. diff --git a/src/installation/live-images/guide.md b/src/installation/live-images/guide.md new file mode 100644 index 0000000..8a7da9e --- /dev/null +++ b/src/installation/live-images/guide.md @@ -0,0 +1,140 @@ +# Installation Guide + +Once you have [downloaded](../index.md#downloading-installation-media) a EvolutionOS +image to install and [prepared](./prep.md) your install media, you are ready to +install EvolutionOS Linux. + +Before you begin installation, you should determine whether your machine boots +using BIOS or UEFI. This will affect how you plan partitions. See [Partitioning +Notes](./partitions.md) for more detail. + +The following features are not supported by the installer script: + +- [LVM](https://en.wikipedia.org/wiki/Logical_volume_management) +- [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup) +- [ZFS](https://en.wikipedia.org/wiki/ZFS) + +## Booting + +Boot your machine from the install media you created. If you have enough RAM, +there is an option on the boot screen to load the entire image into ram, which +will take some time but speed up the rest of the install process. + +Once the live image has booted, it will autologin and run + +``` +# evolution-installer +``` + +The following sections will detail each screen of the installer. + +## Keyboard + +Select the keymap for your keyboard; standard "qwerty" keyboards will generally +use the "us" keymap. + +## Network + +Select your primary network interface. If you do not choose to use DHCP, you +will be prompted to provide an IP address, gateway, and DNS servers. + +If you choose a wireless network interface, you will be prompted to provide the +SSID, encryption type (`wpa` or `wep`), and password. If `evolution-installer` fails +to connect to your network, you may need to exit the installer and configure it +manually using [wpa_supplicant](../../config/network/wpa_supplicant.md) and +[dhcpcd](../../config/network/index.md#dhcpcd) before continuing. + +## Source + +To install packages provided on the install image, select `Local`. Otherwise, +you may select `Network` to download the latest packages from the EvolutionOS +repository. + +> **Warning:** If you are installing the desktop environment from the xfce +> image, you MUST choose `Local` for the source! + +## Hostname + +Select a hostname for your computer (that is all lowercase, with no spaces.) + +## Locale + +Select your default locale settings. This option is for glibc only, as musl does +not currently support locales. + +## Timezone + +Select your timezone based on standard timezone options. + +## Root password + +Enter and confirm your `root` password for the new installation. The password +will not be shown on screen. + +## User account + +Choose a login (default `evolution`) and a descriptive name for that login. Then +enter and confirm the password for the new user. You will then be prompted to +verify the groups for this new user. They are added to the `wheel` group by +default and will have `sudo` access. Default groups and their descriptions are +listed [here](../../config/users-and-groups.html#default-groups). + +Login names have some restrictions, as described in +[useradd(8)](https://man.voidlinux.org/useradd.8#CAVEATS). + +## Bootloader + +Select the disk to install a bootloader on when EvolutionOS is installed. You may +select `none` to skip this step and install a bootloader manually after +completing the installation process. If installing a bootloader, you will also +be asked whether or not you want a graphical terminal for the GRUB menu. + +## Partition + +Next, you will need to partition your disks. EvolutionOS not provide a preset +partition scheme, so you will need to create your partitions manually with +[cfdisk(8)](https://man.voidlinux.org/cfdisk.8). You will be prompted with a +list of disks. Select the disk you want to partition and the installer will +launch `cfdisk` for that disk. Remember you must write the partition table to +the drive before you exit the partition editor. + +If using UEFI, it is recommended you select GPT for the partition table and +create a partition (typically between 200MB-1GB) of type `EFI System`, which +will be mounted at `/boot/efi`. + +If using BIOS, it is recommended you select MBR for the partition table. +Advanced users may use GPT but will need to [create a special BIOS +partition](./partitions.md#bios-system-notes) for GRUB to boot. + +See the [Partitioning Notes](./partitions.md) for more details about +partitioning your disk. + +## Filesystems + +Create the filesystems for each partition you have created. For each partition +you will be prompted to choose a filesystem type, whether you want to create a +new filesystem on the partition, and a mount point, if applicable. When you are +finished, select `Done` to return to the main menu. + +If using UEFI, create a `vfat` filesystem and mount it at `/boot/efi`. + +## Review settings + +It is a good idea to review your settings before proceeding. Use the right arrow +key to select the settings button and hit ``. All your selections will be +shown for review. + +## Install + +Selecting `Install` from the menu will start the installer. The installer will +create all the filesystems selected, and install the base system packages. It +will then generate an initramfs and install a GRUB2 bootloader to the bootable +partition. + +These steps will all run automatically, and after the installation is completed +successfully, you can reboot into your new EvolutionOS install! + +## Post installation + +After booting into your EvolutionOS installation for the first time, [perform a system +update](../../xbps/index.md#updating). diff --git a/src/installation/live-images/index.md b/src/installation/live-images/index.md new file mode 100644 index 0000000..3407ad2 --- /dev/null +++ b/src/installation/live-images/index.md @@ -0,0 +1,80 @@ +# Live Installers + +EvolutionOS provides live installer images containing a base set of utilities, an +installer program, and package files to install a new EvolutionOS system. These live +images are also useful for repairing a system that is not able to boot or +function properly. + +There are `x86_64` images for both `glibc` and `musl` based systems. There are +also images for `i686`, but only `glibc` is supported for this architecture. +Live installers are not provided for other architectures. Users of other +architectures will need to use rootfs tarballs, or perform an installation +manually. + +## Installer images + +EvolutionOS releases two types of images: base images and xfce images. Linux beginners +are encouraged to try one of the more full-featured xfce images, but more +advanced users may often prefer to start from a base image to install only the +packages they need. + +### Base images + +The base images provide only a minimal set of packages to install a usable EvolutionOS +system. These base packages are only those needed to configure a new machine, +update the system, and install additional packages from repositories. + +### Xfce image + +The xfce image includes a full desktop environment, web browser, and basic +applications configured for that environment. The only difference from the base +images is the additional packages and services installed. + +The following software is included: + +- **Window manager:** xfwm4 +- **File manager:** Thunar +- **Web Browser:** Firefox +- **Terminal:** xfce4-terminal +- **Plain text editor:** Mousepad +- **Image viewer:** Ristretto +- **Other:** Bulk rename, Orage Globaltime, Orage Calendar, Task Manager, Parole + Media Player, Audio Mixer, MIME type editor, Application finder + +The install process for the xfce image is the same as the base images, except +that you **must** select the `Local` source when installing. If you select +`Network` instead, the installer will download and install the latest version of +the base system, without any additional packages included on the live image. + +## Accessibility support + +All EvolutionOS images support the console screenreader +[espeakup](https://man.voidlinux.org/espeakup.8) and the console braille display +driver [brltty](https://man.voidlinux.org/brltty.1). These services can be +enabled at boot by pressing `s` in the bootloader menu to enable accessibility +support. On UEFI-based systems, GRUB is the bootloader, and it will play a +two-tone chime when the menu is available. On BIOS-based systems and UEFI +systems in legacy/compatibility mode, SYSLINUX is the bootloader, and no chime +is played. SYSLINUX also requires pressing the enter key after pressing `s`. The +hotkey `r` will also boot with accessibility support, but will load the live ISO +into RAM. + +After booting into the installer image with accessibility support enabled, if +there are multiple soundcards detected, a short audio menu allows for the +selection of the soundcard for the screenreader. Press enter when the beep for +the desired soundcard is heard to select it. + +If the `Local` installation source is selected in the installer, `espeakup` and +`brltty` will also be installed and enabled on the installed system if enabled +in the live environment. + +The xfce image also supports the graphical screenreader +[orca](https://man.voidlinux.org/orca.1). This can be enabled by pressing `Win + +R` and entering `orca -r`. Orca will also be available on the installed system +if the `Local` installation source is selected. + +## Kernel Command-line Parameters + +EvolutionOS installer images support several kernel command-line arguments that can +change the behavior of the live system. See [the evolution-installer README for a full +list](https://github.com/evolution-linux/evolution-installer#kernel-command-line-parameters). diff --git a/src/installation/live-images/partitions.md b/src/installation/live-images/partitions.md new file mode 100644 index 0000000..a3f843a --- /dev/null +++ b/src/installation/live-images/partitions.md @@ -0,0 +1,66 @@ +# Partitioning Notes + +Partitioning for a modern Linux distribution is generally very simple, however +the introduction of GPT and UEFI booting does bring new complexity to the +process. When creating your new partition table you will need a partition for +the root filesystem, along with a swap partition and possibly another partition +or two to facilitate booting, if required. + +Note that if the disk has already been initialized, the top of the `cfdisk` +screen will show the partition layout already present: `Label: dos` for the MBR +scheme, `Label: gpt` for the GPT scheme. If you just want to erase the partition +table before starting the installer, use `wipefs(8)`. Otherwise, you can run +`cfdisk(8)` manually with the `-z` option to start with an uninitialized disk +layout; `cfdisk` will prompt you for the label type before continuing to the +main screen. + +The following sections will detail the options for partition configuration. + +## BIOS system notes + +It is recommended that you create an MBR partition table if you are using a BIOS +boot system. This will limit the number of partitions you create to four. + +It is possible to use a GPT partition table on a BIOS system, but GRUB will +require a special partition to boot properly. This partition should be at the +beginning of your disk and have a size of 1MB, with type `BIOS boot` (GUID +`21686148-6449-6E6F-744E-656564454649`). Don't create any filesystem in it. GRUB +should then install itself successfully. + +## UEFI system notes + +UEFI users are recommended to create a GPT partition table. UEFI booting with +GRUB also requires a special partition of the type `EFI System` with a `vfat` +filesystem mounted at `/boot/efi`. A reasonable size for this partition could be +between 200MB and 1GB. With this partition setup during the live image +installation, the installer should successfully set up the bootloader +automatically. + +## Swap partitions + +A swap partition is not strictly required, but recommended for systems with low +RAM. If you want to use hibernation, you will need a swap partition. The +following table has recommendations for swap partition size. + +| System RAM | Recommended swap space | Swap space if using hibernation | +|------------|------------------------|---------------------------------| +| < 2GB | 2x the amount of RAM | 3x the amount of RAM | +| 2-8GB | Equal to amount of RAM | 2x the amount of RAM | +| 8-64GB | At least 4GB | 1.5x the amount of RAM | +| 64GB | At least 4GB | Hibernation not recommended | + +## Boot partition (optional) + +On most modern systems, a separate `/boot` partition is no longer necessary to +boot properly. If you choose to use one, note that EvolutionOS does not remove old +kernels after updates by default and also that the kernel tends to increase in +size with each new version, so plan accordingly (e.g. `/boot` with one Linux 5.x +`x86_64` kernel and GRUB occupies about 60MB). + +## Other partitions + +It is fine to install your system with only a large root partition, but you may +create other partitions if you want. One helpful addition could be a separate +partition for your `/home` directory. This way if you need to reinstall EvolutionOS (or +another distribution) you can save the data and configuration files in your home +directory for your new system. diff --git a/src/installation/live-images/prep.md b/src/installation/live-images/prep.md new file mode 100644 index 0000000..7085ea6 --- /dev/null +++ b/src/installation/live-images/prep.md @@ -0,0 +1,76 @@ +# Prepare Installation Media + +After [downloading a live image](../index.md#downloading-installation-media), it +must be written to bootable media, such as a USB drive, SD card, or CD/DVD. + +## Create a bootable USB drive or SD card on Linux + +### Identify the Device + +Before writing the image, identify the device you'll write it to. You can do +this using [fdisk(8)](https://man.voidlinux.org/man8/fdisk.8). After connecting +the storage device, identify the device path by running: + +``` +# fdisk -l +Disk /dev/sda: 7.5 GiB, 8036286464 bytes, 15695872 sectors +Disk model: Your USB Device's Model +Units: sectors of 1 * 512 = 512 bytes +Sector size (logical/physical): 512 bytes / 512 bytes +I/O size (minimum/optimal): 512 bytes / 512 bytes +``` + +In the example above, the output shows the USB device as `/dev/sda`. On Linux, +the path to the device will typically be in the form of `/dev/sdX` (where X is a +letter) for USB devices, `/dev/mmcblkX` for SD cards, or other variations +depending on the device. You can use the model and size (`7.5GiB` above, after +the path) to identify the device if you're not sure what path it will have. + +Once you've identified the device you'll use, ensure it's **not** mounted by +unmounting it with [umount(8)](https://man.voidlinux.org/man8/umount.8): + +``` +# umount /dev/sdX +umount: /dev/sdX: not mounted. +``` + +### Write the live image + +The [dd(1)](https://man.voidlinux.org/man1/dd.1) command can be used to copy a +live image to a storage device. Using `dd`, write the live image to the device: + +**Warning**: this will destroy any data currently on the referenced device. +Exercise caution. + +``` +# dd bs=4M if=/path/to/x86_64.iso of=/dev/sdX +90+0 records in +90+0 records out +377487360 bytes (377 MB, 360 MiB) copied, 0.461442 s, 818 MB/s +``` + +`dd` won't print anything until it's completed (or if it failed), so, depending +on the device, this can take a few minutes or longer. You can enable printing by +adding `status=progress` to the command if using GNU coreutils `dd`. + +Finally, ensure all data is flushed before disconnecting the device: + +``` +$ sync +``` + +The number of records, amount copied, and rates will all vary depending on the +device and the live image you chose. + +## Burning to a CD or DVD + +Any disk burning application should be capable of writing the `.iso` file to a +CD or DVD. The following free software applications are available +(cross-platform support may vary): + +- [Brasero](https://wiki.gnome.org/Apps/Brasero/) +- [K3B](https://userbase.kde.org/K3b) +- [Xfburn](https://docs.xfce.org/apps/xfburn/start) + +It should be noted that, with a CD or DVD, live sessions will be less responsive +than with a USB stick or hard drive. diff --git a/src/installation/musl.md b/src/installation/musl.md new file mode 100644 index 0000000..7eb9071 --- /dev/null +++ b/src/installation/musl.md @@ -0,0 +1,33 @@ +# musl + +[musl](https://musl.libc.org/) is a libc implementation which strives to be +lightweight, fast, simple, and correct. + +EvolutionOS supports musl by using it in its codebase for all target +platforms (although binary packages are not available for i686). Additionally, +all compatible packages in our official repositories are available with +musl-linked binaries in addition to their glibc counterparts. + +Currently, there are nonfree and debug sub-repositories for musl, but no +multilib sub-repo. + +## Incompatible software + +musl practices very strict and minimal standard compliance. Many commonly used +platform-specific extensions are not present. Because of this, it is common for +software to need modification to compile and/or function properly. EvolutionOS +developers work to patch such software and hopefully get portability/correctness +changes accepted into the upstream projects. + +Proprietary software usually supports only glibc systems, though sometimes such +applications are available as +[flatpaks](../config/external-applications.md#flatpak) and can be run on a musl +system. In particular, the [proprietary NVIDIA +drivers](../config/graphical-session/graphics-drivers/nvidia.md#nvidia-proprietary-driver) +do not support musl, which should be taken into account when evaluating hardware +compatibility. + +### glibc chroot + +Software requiring glibc can be run in a glibc +[chroot](../config/containers-and-vms/chroot.md). diff --git a/src/theme/book.js b/src/theme/book.js new file mode 100644 index 0000000..853247b --- /dev/null +++ b/src/theme/book.js @@ -0,0 +1,104 @@ +"use strict"; + +// Fix back button cache problem +window.onunload = function () { }; + +(function sidebar() { + var html = document.querySelector("html"); + var sidebar = document.getElementById("sidebar"); + var sidebarLinks = document.querySelectorAll('#sidebar a'); + var sidebarToggleButton = document.getElementById("sidebar-toggle"); + var firstContact = null; + + function showSidebar() { + html.classList.remove('sidebar-hidden') + html.classList.add('sidebar-visible'); + Array.from(sidebarLinks).forEach(function (link) { + link.setAttribute('tabIndex', 0); + }); + sidebarToggleButton.setAttribute('aria-expanded', true); + sidebar.setAttribute('aria-hidden', false); + try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { } + } + + function hideSidebar() { + html.classList.remove('sidebar-visible') + html.classList.add('sidebar-hidden'); + Array.from(sidebarLinks).forEach(function (link) { + link.setAttribute('tabIndex', -1); + }); + sidebarToggleButton.setAttribute('aria-expanded', false); + sidebar.setAttribute('aria-hidden', true); + try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { } + } + + // Toggle sidebar + sidebarToggleButton.addEventListener('click', function sidebarToggle() { + if (html.classList.contains("sidebar-hidden")) { + showSidebar(); + } else if (html.classList.contains("sidebar-visible")) { + hideSidebar(); + } else { + if (getComputedStyle(sidebar)['transform'] === 'none') { + hideSidebar(); + } else { + showSidebar(); + } + } + }); + + document.addEventListener('touchstart', function (e) { + firstContact = { + x: e.touches[0].clientX, + time: Date.now() + }; + }, { passive: true }); + + document.addEventListener('touchmove', function (e) { + if (!firstContact) + return; + + var curX = e.touches[0].clientX; + var xDiff = curX - firstContact.x, + tDiff = Date.now() - firstContact.time; + + if (tDiff < 250 && Math.abs(xDiff) >= 150) { + if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300)) + showSidebar(); + else if (xDiff < 0 && curX < 300) + hideSidebar(); + + firstContact = null; + } + }, { passive: true }); + + // Scroll sidebar to current active section + var activeSection = sidebar.querySelector(".active"); + if (activeSection) { + sidebar.scrollTop = activeSection.offsetTop; + } +})(); + +(function chapterNavigation() { + document.addEventListener('keydown', function (e) { + if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; } + if (window.search && window.search.hasFocus()) { return; } + + switch (e.key) { + case 'ArrowRight': + e.preventDefault(); + var nextButton = document.querySelector('.nav-chapters.next'); + if (nextButton) { + window.location.href = nextButton.href; + } + break; + case 'ArrowLeft': + e.preventDefault(); + var previousButton = document.querySelector('.nav-chapters.previous'); + if (previousButton) { + window.location.href = previousButton.href; + } + break; + } + }); +})(); diff --git a/src/theme/css/general.css b/src/theme/css/general.css new file mode 100644 index 0000000..9dc4566 --- /dev/null +++ b/src/theme/css/general.css @@ -0,0 +1,477 @@ +body { + font-family: Arial, sans-serif; + text-align: center; + padding: 20px; + background-color: #e6e6e6; + min-width: 700px; +} + +h1, h2, h3, h4, h5, h6 { + color: #333; +} + +a { + color: #008040; + text-decoration: none; + text-decoration: underline; +} + +a:hover { + color: #008040; +} + +code { + background: #fdf6e3; + padding: 2px 4px; + border-radius: 4px; + white-space: pre-wrap; + overflow-wrap: break-word; +} + +pre code { + padding: 0; + border-radius: 0; +} + +pre { + padding: .5em; + margin: 1em 0; + background: #fdf6e3; + border: 1px solid #ccc; + border-radius: 4px; +} + +blockquote { + margin: 20px 0; + padding: 0 20px; + padding-left: 1em; + background: #ebf4ef; + border: 1px solid #d1e6da; + border-left: none; + border-right: none; +} + +li.js-unavailable { + background-color: #f6cf68; + border-radius: 10px; + margin-left: 1em; + padding-left: 1em; + padding-right: 1em; +} + +table { + border-collapse: collapse; + display: block; + overflow-y: auto; +} + +table td { + padding: 3px 20px; + border: 1px #fafafa solid; +} + +table thead { + background: #fafafa; +} + +table thead td { + font-weight: 700; + border: none; +} + +table thead tr { +} + +/* Alternate background colors for rows */ +table tbody tr:nth-child(2n) { + background: #fafafa; +} + +svg { + position: relative; + top: .125em; + width: 1em; + height: auto; +} + +.hidden { + display: none; +} + +.icon-button { + min-height: 60px; + max-height: 60px; + border: none; + background: none; + cursor: pointer; + padding: 1em; +} + +/* void navigation */ + +#void-nav { + width: 100%; + min-height: 60px; + max-height: 60px; + background-color: #41e38e; + padding: 5px; + display: flex; + align-items: center; + position: fixed; + top: 0; + left: 0; + right: 0; + min-width: 700px; + overflow-y: hide; + overflow-x: auto; + white-space: nowrap; +} + +#void-nav button, +#void-nav label { + fill: #e6e6e6; + height: 50px; + display: block; + line-height: 50px; + padding: 0 15px; + font-size: 1.2em; + transition: background-color 0.3s ease; +} + +#void-nav ul { + list-style: none; + margin: 0; + padding: 0; +} + +#void-nav ul#nav-right { + margin-left: auto; +} + +#void-nav ul li { + display: inline-block; +} + +#void-nav ul li a { + color: #fff; + display: block; + padding: 0 15px; + line-height: 50px; + font-size: 1.2em; + text-decoration: none; +} + +#void-nav ul li ao { + background-color: #41e38e; + color: #fff; + padding: 18px 10px; + font-size: 20px; + border: none; + cursor: pointer; + text-decoration: none; + transition: background-color 0.3s ease; + min-height: 60px; + max-height: 60px; +} + +#void-nav ul li ab { + background-color: #41e38e; + color: #fff; + padding: 7px 0px; + font-size: 20px; + border: none; + cursor: pointer; + text-decoration: none; + transition: background-color 0.3s ease; + min-height: 46px; + display: block; +} + +#void-nav ul li ab:hover { + background-color: #008040; +} + +#void-nav ul li a:hover, +#void-nav ul li a:focus, +#void-nav button:hover, +#void-nav button:focus, +#void-nav label:hover, +#void-nav label:focus { + background-color: #008040; +} + +#void-nav ul li ao:hover { + min-height: 60px; + max-height: 60px; + background-color: #008040; +} + +#skip-to-content { + position: absolute; + left: -999px; + top: -999px; +} + +#skip-to-content:active, +#skip-to-content:focus { + position: relative; + left: 0; + top: 0; +} + +/* sidebar */ + +.sidebar-hidden #sidebar { + background: #008040; + display: none; +} + +#sidebar { + border-top: 40px solid transparent; + padding: .5em; + background: #008040; + font-size: 0.875em; +} + +#sidebar ol { + list-style: none; + margin: 0; +} + +#sidebar ol.chapter { + padding: 0; + line-height: 2.2em; +} + +#sidebar ol.section { + padding-left: 20px; + line-height: 1.9em; +} + +#sidebar a { + color: #e6e6e6; + display: block; +} + +#sidebar a:hover { + color: #c8c8c8; + text-decoration: none; +} + +#sidebar a.active { + color: #e6e6e6; +} + +#sidebar-toggle { + display: none; +} + +/* search */ + +#searchbar { + width: 100%; + padding: 10px 16px; + margin: 5px 0; + border-radius: 3px; + border: 1px solid #aaa; +} + +#searchresults-header { + font-weight: bold; + font-size: 1em; + padding: 18px 0 0 5px; +} + +ul#searchresults { + list-style: none; + padding-left: 20px; +} + +ul#searchresults li { + margin: 10px 0px; + padding: 2px; + border-radius: 2px; +} + +ul#searchresults span.teaser { + display: block; + clear: both; + margin: 5px 0 0 20px; + font-size: 0.8em; +} + +/* chapter navigation */ + +#nav-wide-wrapper { + background-color: #41e38e; + max-width: 800px; + margin: 0 auto; + margin-top: 50px; +} + +.previous { + float: left; +} + +.next { + float: right; + right: 15px; +} + +.nav-chapters { + fill: #ccc; + text-align: center; + text-decoration: none; + display: block; + max-width: 150px; + min-width: 90px; +} + +.nav-chapters:hover { + text-decoration: none; + fill: #333; +} + +.nav-chapters svg { + margin: 0 auto; + width: 1.5em; +} + +/* layout */ + +body { + box-sizing: border-box; +} + +#content { + display: flex; + flex-direction: row; + width: 100%; +} + +#page-wrapper { + border-top: 40px solid transparent; + --content-padding: 10px; + padding: 0 var(--content-padding); + width: calc(100% - var(--content-padding) * 2); +} + +#search-wrapper { + border-top: 40px solid transparent; + width: 100%; + max-width: 800px; + margin: 0 auto; +} +#page-wrapper main { + width: 100%; + max-width: 800px; + margin: 0 auto; +} + +#sidebar { + max-width: 300px; + flex-shrink: 0; +} + +/* 300px + 800px + 2*90px + 15px */ +@media only screen and (min-width: 1295px) { + .sidebar-visible #nav-wide-wrapper { + background-color: #41e38e; + max-width: none; + margin: 0; + } + .sidebar-visible .nav-chapters { + background: none; + position: fixed; + top: 50px; + bottom: 0; + margin: 0; + justify-content: center; + align-content: center; + display: flex; + flex-direction: column; + } +} + +/* 800px + 2*90px + 15px */ +@media only screen and (min-width: 995px) { + .sidebar-hidden #nav-wide-wrapper { + background-color: #41e38e; + max-width: none; + margin: 0; + } + .sidebar-hidden .nav-chapters { + background: none; + position: fixed; + top: 50px; + bottom: 0; + margin: 0; + justify-content: center; + align-content: center; + display: flex; + flex-direction: column; + } +} + +/* Dark Mode Styles */ + +body.dark-mode { + background-color: #222; + color: #fff; +} + + +body.dark-mode h1, +body.dark-mode h2, +body.dark-mode h3, +body.dark-mode h4, +body.dark-mode h5, +body.dark-mode h6 { + color: #fff; +} + +body.dark-mode code { + background-color: #5c5c5c; +} + +body.dark-mode pre { + background: #5c5c5c; +} + +#void-nav.dark-mode label { + color: #6c6c6c; +} + +.dark-mode table tbody tr:nth-child(2n) { + background: #5c5c5c; +} + +ao.dark-mode-button { + min-height: 60px; + max-height: 60px; + background-color: #41e38e; + color: #fff; + padding: 18px 20px; + font-size: 20px; + border: none; + cursor: pointer; + text-decoration: none; + transition: background-color 0.3s ease; +} + +ao.dark-mode-button:hover { + + background-color: #008040; +} + +img { + max-height: 40px; + margin-right: 10px; + margin-left: 10px; +} + +.container { + display: flex; + justify-content: flex-end; +} + diff --git a/src/theme/css/print.css b/src/theme/css/print.css new file mode 100644 index 0000000..717ccb8 --- /dev/null +++ b/src/theme/css/print.css @@ -0,0 +1,54 @@ + +#sidebar, +#menu-bar, +.nav-chapters, +.mobile-nav-chapters { + display: none; +} + +#page-wrapper.page-wrapper { + transform: none; + margin-left: 0px; + overflow-y: initial; +} + +#content { + max-width: none; + margin: 0; + padding: 0; +} + +.page { + overflow-y: initial; +} + +code { + background-color: #666666; + border-radius: 5px; + + /* Force background to be printed in Chrome */ + -webkit-print-color-adjust: exact; +} + +pre > .buttons { + z-index: 2; +} + +a, a:visited, a:active, a:hover { + color: #4183c4; + text-decoration: none; +} + +h1, h2, h3, h4, h5, h6 { + page-break-inside: avoid; + page-break-after: avoid; +} + +pre, code { + page-break-inside: avoid; + white-space: pre-wrap; +} + +svg { + display: none !important; +} diff --git a/src/theme/favicon.png b/src/theme/favicon.png new file mode 100644 index 0000000..9381f93 Binary files /dev/null and b/src/theme/favicon.png differ diff --git a/src/theme/index.hbs b/src/theme/index.hbs new file mode 100644 index 0000000..3772a1b --- /dev/null +++ b/src/theme/index.hbs @@ -0,0 +1,251 @@ + + + + + + EvolutionOS Wiki + + + + + + + + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + +
+ {{#if search_enabled}} + + {{/if}} + +
+ {{{ content }}} +
+ + +
+
+ + {{#if livereload}} + + + {{/if}} + + {{#if search_js}} + + + + {{/if}} + + + + + + + + + diff --git a/src/xbps/advanced-usage.md b/src/xbps/advanced-usage.md new file mode 100644 index 0000000..523a167 --- /dev/null +++ b/src/xbps/advanced-usage.md @@ -0,0 +1,103 @@ +# Advanced Usage + +## Downgrading + +XBPS allows you to downgrade a package to a specific package version. + +### Via xdowngrade + +The easiest way to downgrade is to use `xdowngrade` from the `xtools` package, +specifying the package version to which you wish to downgrade: + +``` +# xdowngrade /var/cache/xbps/pkg-1.0_1.xbps +``` + +### Via XBPS + +XBPS can be used to downgrade to a package version that is no longer available +in the repository index. + +If the package version had been installed previously, it will be available in +`/var/cache/xbps/`. If not, it will need to be obtained from elsewhere; for the +purposes of this example, it will be assumed that the package version has been +added to `/var/cache/xbps/`. + +First add the package version to your local repository: + +``` +# xbps-rindex -a /var/cache/xbps/pkg-1.0_1.xbps +``` + +Then downgrade with `xbps-install`: + +``` +# xbps-install -R /var/cache/xbps/ -f pkg-1.0_1 +``` + +The `-f` flag is necessary to force downgrade/re-installation of an already +installed package. + +## Holding packages + +To prevent a package from being updated during a system update, use +[xbps-pkgdb(1)](https://man.voidlinux.org/xbps-pkgdb.1): + +``` +# xbps-pkgdb -m hold +``` + +The hold can be removed with: + +``` +# xbps-pkgdb -m unhold +``` + +## Repository-locking packages + +If you've used `xbps-src` to build and install a package from a customized +template, or with custom build options, you may wish to prevent system updates +from replacing that package with a non-customized version. To ensure that a +package is only updated from the same repository used to install it, you can +*repolock* it via [xbps-pkgdb(1)](https://man.voidlinux.org/xbps-pkgdb.1): + +``` +# xbps-pkgdb -m repolock +``` + +To remove the repolock: + +``` +# xbps-pkgdb -m repounlock +``` + +## Ignoring Packages + +Sometimes you may wish to remove a package whose functionality is being provided +by another package, but will be unable to do so due to dependency issues. For +example, you may wish to use [doas(1)](https://man.voidlinux.org/doas.1) instead +of [sudo(8)](https://man.voidlinux.org/sudo.8), but will be unable to remove the +`sudo` package due to it being a dependency of the `base-system` package. To +remove it, you will need to *ignore* the `sudo` package. + +To ignore a package, add an appropriate `ignorepkg` entry in an +[xbps.d(5)](https://man.voidlinux.org/xbps.d.5) configuration file. For example: + +``` +ignorepkg=sudo +``` + +You will then be able to remove the `sudo` package using +[xbps-remove(1)](https://man.voidlinux.org/xbps-remove.1). + +## Virtual Packages + +Virtual packages can be created with +[xbps.d(5)](https://man.voidlinux.org/xbps.d.5) `virtualpkg` entries. Any +request to the virtual package will be resolved to the real package. For +example, to create a `linux` virtual package which will resolve to the +`linux5.6` package, create an `xbps.d` configuration file with the contents: + +``` +virtualpkg=linux:linux5.6 +``` diff --git a/src/xbps/index.md b/src/xbps/index.md new file mode 100644 index 0000000..710b94e --- /dev/null +++ b/src/xbps/index.md @@ -0,0 +1,127 @@ +# XBPS Package Manager + +The X Binary Package System (XBPS) is a fast package manager that has been +designed and implemented from scratch. XBPS is managed by the Void Linux team +and developed at . + +Most general package management is done with the following commands: + +- [xbps-query(1)](https://man.voidlinux.org/xbps-query.1) searches for and + displays information about packages installed locally, or, if used with the + `-R` flag, packages contained in repositories. +- [xbps-install(1)](https://man.voidlinux.org/xbps-install.1) installs and + updates packages, and syncs repository indexes. +- [xbps-remove(1)](https://man.voidlinux.org/xbps-remove.1) removes installed + packages, and can also remove orphaned packages and cached package files. +- [xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) runs the + configuration steps for installed packages, and can be used to reconfigure + certain packages after changes in their configuration files. The latter + usually requires the `--force` flag. +- [xbps-alternatives(1)](https://man.voidlinux.org/xbps-alternatives.1) lists or + sets the alternatives provided by installed packages. Alternatives is a + system which allows multiple packages to provide common functionality through + otherwise conflicting files, by creating symlinks from the common paths to + package-specific versions that are selected by the user. +- [xbps-pkgdb(1)](https://man.voidlinux.org/xbps-pkgdb.1) can report and fix + issues in the package database, as well as modify it. +- [xbps-rindex(1)](https://man.voidlinux.org/xbps-rindex.1) manages local binary + package repositories. + +Most questions can be answered by consulting the man pages for these tools, +together with the [xbps.d(5)](https://man.voidlinux.org/xbps.d.5) man page. + +To learn how to build packages from source, refer to [the README for the +evolution-packages +repository](https://github.com/evolution-linux/evolution-packages/blob/master/README.md). + +## Updating + +Like any other system, it is important to keep Evolution up-to-date. Use +[xbps-install(1)](https://man.voidlinux.org/xbps-install.1) to update: + +``` +# xbps-install -Su +``` + +XBPS must use a separate transaction to update itself. If your update includes +the `xbps` package, you will need to run the above command a second time to +apply the rest of the updates. + +### Restarting Services + +XBPS does not restart services when they are updated. This task is left to the +administrator, so they can orchestrate maintenance windows, ensure reasonable +backup capacity, and generally be present for service upgrades. + +To find processes running different versions than are present on disk, use the +`xcheckrestart` tool provided by the `xtools` package: + +``` +$ xcheckrestart +11339 /opt/google/chrome/chrome (deleted) (google-chrome) +``` + +`xcheckrestart` will print out the PID, path to the executable, status of the +path that was launched (almost always `deleted`) and the process name. + +`xcheckrestart` can and should be run as an unprivileged user. + +### Kernel Panic After Update + +If you get a kernel panic after an update, it is likely your system ran out of +space in `/boot`. Refer to "[Removing old +kernels](../config/kernel.md#removing-old-kernels)" for further information. + +## Finding Files and Packages + +To search available repositories for packages, use +[xbps-query(1)](https://man.voidlinux.org/xbps-query.1): + +``` +$ xbps-query -Rs +``` + +The `-R` flag specifies that repositories should be searched. Without it, `-s` +searches for locally-installed packages. + +If you can't find a file or program you expected to find after installing a +package, you can use [xbps-query(1)](https://man.voidlinux.org/xbps-query.1) to +list the files provided by that package: + +``` +$ xbps-query -f +``` + +The `xtools` package contains the +[xlocate(1)](https://man.voidlinux.org/xlocate.1) utility. `xlocate` works like +[locate(1)](https://man.voidlinux.org/locate.1), but for files in the Evolution +package repositories: + +``` +$ xlocate -S +Fetching objects: 11688, done. +From https://repo-default.voidlinux.org/xlocate/xlocate + + e122c3634...a2659176f master -> master (forced update) +$ xlocate xlocate +xtools-0.59_1 /usr/bin/xlocate +xtools-0.59_1 /usr/share/man/man1/xlocate.1 -> /usr/share/man/man1/xtools.1 +``` + +It is also possible to use +[xbps-query(1)](https://man.voidlinux.org/xbps-query.1) to find files, though +this is strongly discouraged: + +``` +$ xbps-query -Ro /usr/bin/xlocate +xtools-0.46_1: /usr/bin/xlocate (regular file) +``` + +This requires `xbps-query` to download parts of every package to find the file. +`xlocate`, however, queries a locally cached index of all files, so no network +access is required. + +To get a list of all installed packages, without their version: + +``` +$ xbps-query -l | awk '{ print $2 }' | xargs -n1 xbps-uhelper getpkgname +``` diff --git a/src/xbps/repositories/custom.md b/src/xbps/repositories/custom.md new file mode 100644 index 0000000..69da1de --- /dev/null +++ b/src/xbps/repositories/custom.md @@ -0,0 +1,33 @@ +# Custom Repositories + +EvolutionOS supports user-created repositories, both local and remote. This is only +recommended for serving custom packages created personally, or packages from +another trusted source. The EvolutionOS project does not support *any* third-party +package repositories - the use of third-party software packages poses very +serious security concerns, and risks serious damage your system. + +## Adding custom repositories + +To add a custom repository, create a file in `/etc/xbps.d`, with the contents: + +``` +repository= +``` + +where `` is either a local directory or a URL to a remote repository. + +For example, to define a remote repository: + +``` +# echo 'repository=http://my.domain.com/repo' > /etc/xbps.d/my-remote-repo.conf +``` + +Remote repositories need to be [signed](./signing.md). +[xbps-install(1)](https://man.voidlinux.org/xbps-install.1) refuses to install +packages from remote repositories if they are not signed. + +To define a local repository: + +``` +# echo 'repository=/path/to/repo' > /etc/xbps.d/my-local-repo.conf +``` diff --git a/src/xbps/repositories/index.md b/src/xbps/repositories/index.md new file mode 100644 index 0000000..db3922b --- /dev/null +++ b/src/xbps/repositories/index.md @@ -0,0 +1,87 @@ +# Repositories + +Repositories are the heart of the XBPS package system. Repositories can be local +or remote. A repository contains binary package files, which may have +signatures, and a data file named `$ARCH-repodata` (e.g. `x86_64-repodata`), +which may also be signed. + +Note that, while local repositories do not require signatures, remote +repositories **must** be signed. + +## The main repository + +The locations of the main repository in relation to a base [mirror +URL](./mirrors/index.md) are: + +- glibc: `/current` +- musl: `/current/musl` +- aarch64 and aarch64-musl: `/current/aarch64` + +There is also an additional repository containing patches at + +https://hectabit.org/evolutionos/pkg + +## Subrepositories + +In addition to the main repository, which is enabled upon installation, EvolutionOS +provides other official repositories maintained by the Void project, but not +enabled by default: + +- nonfree: contains software packages with non-free licenses +- multilib: contains 32-bit libraries for 64-bit systems (glibc only) +- multilib/nonfree: contains non-free multilib packages +- debug: contains debugging symbols for packages + +These repositories can be enabled via the installation of the relevant package. +These packages only install a repository configuration file in +`/usr/share/xbps.d`. + +### nonfree + +EvolutionOS has a `nonfree` repository for packages that don't have free licenses. It +can be enabled by installing the `void-repo-nonfree` package. + +Packages can end up in the `nonfree` repository for a number of reasons: + +- Non-free licensed software with released source-code. +- Software released only as redistributable binary packages. +- Patented technology, which may or may not have an (otherwise) open + implementation. + +### multilib + +The `multilib` repository provides 32-bit packages as a compatibility layer +inside a 64-bit system. It can be enabled by installing the `void-repo-multilib` +package. + +These repositories are only available for `x86_64` systems running the `glibc` C +library. + +### multilib/nonfree + +The `multilib/nonfree` repository provides additional 32-bit packages which have +non-free licenses. It can be enabled by installing the +`void-repo-multilib-nonfree` package. + +### debug + +EvolutionOS packages come without debugging symbols. If you want to debug +software or look at a core dump you will need the debugging symbols. These +packages are contained in the debug repository. It can be enabled by installing +the `void-repo-debug` package. + +Once enabled, symbols may be obtained for `` by installing +`-dbg`. + +#### Finding debug dependencies + +The `xtools` package contains the [xdbg(1)](https://man.voidlinux.org/xtools.1) +utility to retrieve a list of debug packages, including dependencies, for a +package: + +``` +$ xdbg bash +bash-dbg +glibc-dbg +# xbps-install -S $(xdbg bash) +``` diff --git a/src/xbps/repositories/mirrors/changing.md b/src/xbps/repositories/mirrors/changing.md new file mode 100644 index 0000000..3835e40 --- /dev/null +++ b/src/xbps/repositories/mirrors/changing.md @@ -0,0 +1,48 @@ +# Changing Mirrors + +Each repository has a file defining the URL for the mirror used. For official +repositories, these files are installed by the package manager in +`/usr/share/xbps.d`, but if duplicate files are found in `/etc/xbps.d`, those +values are used instead. + +## xmirror + +To easily modify the currently selected mirror, +[xmirror(1)](https://man.voidlinux.org/xmirror.1) (from the `xmirror` package) +can be used. This utility takes care of all steps for updating the selected +mirror. + +## Manual Method + +Alternatively, this can be done manually: + +To modify mirror URLs cleanly, copy all the repository configuration files to +`/etc/xbps.d` and change the URLs in each copied repository file. + +``` +# mkdir -p /etc/xbps.d +# cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/ +# sed -i 's|https://repo-default.voidlinux.org||g' /etc/xbps.d/*-repository-*.conf +``` + +After changing the URLs, you must synchronize xbps with the new mirrors: + +``` +# xbps-install -S +``` + +You should see the new repository URLs while synchronizing. You can also use +`xbps-query` to verify the repository URLs, but only after they have been +synchronized: + +``` +$ xbps-query -L + 9970 https://repo-default.voidlinux.org/current (RSA signed) + 27 https://repo-default.voidlinux.org/current/multilib/nonfree (RSA signed) + 4230 https://repo-default.voidlinux.org/current/multilib (RSA signed) + 47 https://repo-default.voidlinux.org/current/nonfree (RSA signed) + 5368 https://repo-default.voidlinux.org/current/debug (RSA signed) +``` + +Remember that repositories added afterwards will also need to be changed, or +they will use the default mirror. diff --git a/src/xbps/repositories/mirrors/index.md b/src/xbps/repositories/mirrors/index.md new file mode 100644 index 0000000..46d3a76 --- /dev/null +++ b/src/xbps/repositories/mirrors/index.md @@ -0,0 +1,93 @@ +# Mirrors + +EvolutionOS uses the Void Linux repos, which maintains mirrors in several +geographic regions for you to use. A fresh install will default to using the +master mirror in Europe, but you may also [select a different mirror](./changing.md) +manually. + +## Tier 0 mirrors + +Tier 0 mirrors contain patches for evolutionOS to work correctly. There is only +one at: + +https://evolution-linux.github.io + +## Tier 1 mirrors + +Tier 1 mirrors are maintained by the Void Linux Infrastructure Team. These +mirrors sync directly from the build-master and will always have the latest +packages available. + +By default XBPS will reach out to which may +map to any tier 1 mirror. + + + +| Repository | Region | Location | +|------------------------------------------------|---------------|--------------------| +| | Global | Fastly Global CDN | +| | Europe | Helsinki, Finland | +| | Europe | Frankfurt, Germany | +| | North America | Chicago, USA | + + +## Tier 2 mirrors + +Tier 2 mirrors sync from a nearby Tier 1 mirror when possible. These mirrors are +not managed by us or the Void team and do not have any guarantees of freshness or completeness +of packages, nor are they required to sync every available architecture or +sub-repository. + +### Globally-available mirrors + + + +| Repository | Region | Location | +|----------------------------------------------------|---------------|------------------------| +| | Asia | Almaty, Kazakhstan | +| | Asia | China | +| | Asia | Beijing, China | +| | Asia | Beijing, China | +| | Asia | Beijing, China | +| | Asia | Shanghai, China | +| | Asia | Singapore | +| | Europe | Denmark | +| | Europe | Denmark | +| | Europe | Greece | +| | Europe | Hungary | +| | Europe | Italy | +| | Europe | Amsterdam, Netherlands | +| | Europe | Warsaw, Poland | +| | Europe | Russia | +| | Europe | Russia | +| | Europe | Sweden | +| | Europe | Sweden | +| | Europe | Bern, Switzerland | +| | North America | California, USA | +| | North America | Kentucky, USA | +| | North America | New York, USA | +| | Oceania | Canberra, Australia | +| | Oceania | Melbourne, Australia | +| | South America | Ouro Preto, Brazil | +| | South America | Pimenta Bueno, Brazil | + +## Tor Mirrors + +EvolutionOS is also mirrored on the Tor network. See [Using Tor +Mirrors](./tor.md) for more information. + +## Creating a mirror + +If you'd like to set up a mirror, and are confident you can keep it reasonably +up-to-date, follow one of the many guides available for mirroring with +[rsync(1)](https://man.voidlinux.org/rsync.1), then submit a pull request to +[the evolution-docs repository](https://centrifuge.hectabit.org/evolutionos/evolution-docs) to add your +mirror to the appropriate mirror table on this page. + +A full mirror requires around 1TB of storage. It is also possible to mirror only +part of the repositories. Excluding debug packages is one way of decreasing the +load on the Tier 1 mirrors, with low impact on users. + +Please keep in mind that we pay bandwidth for all data sent out from the Tier 1 +mirrors. You can respect this by only mirroring if your use case for your mirror +will offset the network throughput consumed by your mirror syncing. diff --git a/src/xbps/repositories/mirrors/tor.md b/src/xbps/repositories/mirrors/tor.md new file mode 100644 index 0000000..d61b5cd --- /dev/null +++ b/src/xbps/repositories/mirrors/tor.md @@ -0,0 +1,98 @@ +# Using Tor Mirrors + +Tor is an anonymizing software that bounces traffic via computers all around the +world. It can provide access to regular sites on the internet or to hidden sites +only available on the network. + +Note that these are tier 1 mirrors, and tier 0 mirrors still need to be on the clearnet. + +The following EvolutionOS Linux Mirrors are available on the Tor Network: + +| Repository | Location | +|----------------------------------------------------------------------------------------|------------| +| | EU: Sweden | + +## Using XBPS with Tor + +XBPS can be made to connect to mirrors using Tor. These mirrors can be normal +mirrors, via exit relays, or, for potentially greater anonymity, hidden service +mirrors on the network. + +XBPS respects the `SOCKS_PROXY` environment variable, which makes it easy to use +via Tor. + +### Installing Tor + +Tor is contained in the `tor` package. + +After having installed Tor, you can start it as your own user: + +``` +$ tor +``` + +or enable its system service. + +By default, Tor will act as a client and open a SOCKS5 proxy on TCP port 9050 on +localhost. + +### Making XBPS connect via the SOCKS proxy + +XBPS reads the `SOCKS_PROXY` environment variable and will use any proxy +specified in it. By simply setting the variable to the address and port of the +proxy opened by the Tor client, all XBPS's connections will go over the Tor +network. + +An example upgrading your system over Tor: + +``` +# export SOCKS_PROXY="socks5://127.0.0.1:9050" +# xbps-install -Su +``` + +### Using a hidden service mirror + +To use a hidden service mirror, the default mirrors need to be overwritten with +configuration files pointing to `.onion`-addresses that are used internally on +the Tor network. XBPS allows overriding repository addresses under +`/etc/xbps.d`. + +Copy your repository files from `/usr/share/xbps.d` to `/etc/xbps.d` and replace +the addresses with that of an onion service (Lysator's onion used as an +example): + +``` +# mkdir -p /etc/xbps.d +# cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/ +# sed -i 's|https://repo-default.voidlinux.org|http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux|g' /etc/xbps.d/*-repository-*.conf +``` + +Tor provides layered end-to-end encryption so HTTPS is not necessary. + +When installing packages, with `SOCKS_PROXY` set like the earlier example, XBPS +should indicate that it is synchronizing the repositories from the onion address +specified in the override: + +``` +# xbps-install -S +[*] Updating `http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux/current/aarch64/nonfree/aarch64-repodata' ... +aarch64-repodata: 4030B [avg rate: 54KB/s] +[*] Updating `http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux/current/aarch64/aarch64-repodata' ... +aarch64-repodata: 1441KB [avg rate: 773KB/s] +``` + +### Security consideration + +It is advisable to set `SOCKS_PROXY` automatically in your environment if you +are using an onion. If the setting is missing, a DNS query for the name of the +hidden service will leak to the configured DNS server. + +To automatically set the environment variable, add it to a file in +`/etc/profile.d`: + +``` +# cat - < /etc/profile.d/socksproxy.sh +#!/bin/sh +export SOCKS_PROXY="socks5://127.0.0.1:9050" +EOF +``` diff --git a/src/xbps/repositories/restricted.md b/src/xbps/repositories/restricted.md new file mode 100644 index 0000000..1af4976 --- /dev/null +++ b/src/xbps/repositories/restricted.md @@ -0,0 +1,33 @@ +# Restricted Packages + +EvolutionOS offers some packages that are officially maintained, but not distributed. +These packages are marked as restricted and must be built from their +[evolution-packages](https://github.com/evolution-linux/evolution-packages) template locally. + +Packages can be restricted from distribution by either the upstream author or +EvolutionOS. EvolutionOS reserves the right to restrict distribution of any package for +effectively any reason, massive size being the most common. Another common +reason is restrictive licensing that does not allow third-party redistribution +of source or binary packages. + +## Building manually + +You can use `xbps-src` in the +[evolution-packages](https://github.com/evolution-linux/evolution-packages) repository to build +the restricted packages from templates. For instructions on building packages +from templates, refer to the +[evolution-packages](https://github.com/evolution-linux/evolution-packages) documentation, and +the ["Quick start" +section](https://github.com/evolution-linux/evolution-packages#quick-start) in particular +. + +Remember that the building of restricted packages must be enabled explicitly by +setting `XBPS_ALLOW_RESTRICTED=yes` in your `xbps-src` configuration (in the +`etc/conf` file in the repository.) + +## Automated building + +There is also a tool, +[xbps-mini-builder](https://github.com/the-maldridge/xbps-mini-builder) which +automates the process of building a list of packages. The script can be called +periodically and will only rebuild packages if their templates have changed. diff --git a/src/xbps/repositories/signing.md b/src/xbps/repositories/signing.md new file mode 100644 index 0000000..5f72c41 --- /dev/null +++ b/src/xbps/repositories/signing.md @@ -0,0 +1,35 @@ +# Signing Repositories + +Remote repositories **must** be signed. Local repositories do not need to be +signed. + +The [xbps-rindex(1)](https://man.voidlinux.org/xbps-rindex.1) tool is used to +sign repositories. + +The private key for signing packages needs to be a PEM-encoded RSA key. The key +can be generated with either +[ssh-keygen(1)](https://man.voidlinux.org/ssh-keygen.1) or +[openssl(1)](https://man.voidlinux.org/openssl.1): + +``` +$ ssh-keygen -t rsa -m PEM -f private.pem +``` + +``` +$ openssl genrsa -out private.pem +``` + +Once the key is generated, the public part of the private key has to be added to +the repository metadata. This step is required only once. + +``` +$ xbps-rindex --privkey private.pem --sign --signedby "I'm Groot" /path/to/repository/dir +``` + +Then sign one or more packages with the following command: + +``` +$ xbps-rindex --privkey private.pem --sign-pkg /path/to/repository/dir/*.xbps +``` + +Note that future packages will not be automatically signed. diff --git a/src/xbps/troubleshooting/common-issues.md b/src/xbps/troubleshooting/common-issues.md new file mode 100644 index 0000000..411a4b1 --- /dev/null +++ b/src/xbps/troubleshooting/common-issues.md @@ -0,0 +1,97 @@ +# Common Issues + +## Verifying RSA keys + +If the Void or EvolutionOS RSA key has changed, +[xbps-install(1)](https://man.voidlinux.org/xbps-install.1) will report the new +key fingerprint and ask you to confirm it: + +``` + repository has been RSA signed by "Tracker-Friendly" +Fingerprint: +Do you want to import this public key? [Y/n] +``` + +To verify the key, ensure the `` matches one of the +fingerprints in both +[evolution-packages](https://github.com/evolution-linux/evolution-packages/tree/master/common/repo-keys) +and [evolution-installer](https://github.com/evolution-linux/evolution-installer/tree/master/keys). + +Tier 0 mirror keys will be found at [a evolution-installer subdirectory](https://github.com/evolution-linux/evolution-installer/tree/master/include/var/db/xbps/) + +## Errors while updating or installing packages + +If there are any errors while updating or installing a new package, make sure +that you are using the latest version of the remote repository index. Running +[xbps-install(1)](https://man.voidlinux.org/xbps-install.1) with the `-S` option +will guarantee that. + +### "Operation not permitted" + +An "Operation not permitted" error, such as: + +``` +ERROR: [reposync] failed to fetch file https://repo-default.voidlinux.org/current/nonfree/x86_64-repodata': Operation not permitted +``` + +can be caused by your system's date and/or time being incorrect. Ensure your +[date and time](../../config/date-time.md) are correct. + +### "Not Found" + +A "Not Found" error, such as: + +``` +ERROR: [reposync] failed to fetch file `https://repo-default.voidlinux.org/current/musl/x86_64-repodata': Not Found +``` + +usually means your XBPS configuration is pointing to the wrong repositories for +your system. Confirm that your [xbps.d(5)](https://man.voidlinux.org/xbps.d.5) +files refer to [the correct repositories](../repositories/index.md). + +### shlib errors + +An "unresolvable shlib" error, such as: + +``` +libllvm8-8.0.1_2: broken, unresolvable shlib `libffi.so.6' +``` + +is probably due to outdated or orphan packages. To check for outdated packages, +simply try to [update your system](../index.md#updating). Orphan packages, on +the other hand, have been removed from the Void or EvolutionOS repos, but are still installed +on your system; they can be removed by running +[xbps-remove(1)](https://man.voidlinux.org/xbps-remove.1) with the `-o` option. + +If you get an error message saying: + +``` +Transaction aborted due to unresolved shlibs +``` + +the repositories are in the staging state, which can happen due to large builds. +The solution is to wait for the builds to finish. You can view the builds' +progress in the [Buildbot's Waterfall +Display](https://build.voidlinux.org/waterfall). + +### repodata errors + +In March 2020, the compression format used for the repository data (repodata) +was changed from gzip to zstd. If XBPS wasn't updated to version `0.54` +(released June 2019) or newer, it is not possible to update the system with it. +Unfortunately, there isn't an error message for this case, but it can be +detected by running `xbps-install` with the `-Sd` flags. The debug message for +this error is shown below. + +``` +[DEBUG] [repo] `//var/db/xbps/https___repo-default_voidlinux_org_current/x86_64-repodata' failed to open repodata archive Invalid or incomplete multibyte or wide character +``` + +In this situation, it is necessary to follow the steps in +[xbps-static](./static.md). + +## Broken systems + +If your system is for some reason broken and can't perform updates or package +installations, using a [statically linked version of xbps](./static.md) to +update and install packages can help you avoid reinstalling the whole system. diff --git a/src/xbps/troubleshooting/index.md b/src/xbps/troubleshooting/index.md new file mode 100644 index 0000000..508984f --- /dev/null +++ b/src/xbps/troubleshooting/index.md @@ -0,0 +1,10 @@ +# Troubleshooting XBPS + +Sometimes the package manager gets in a weird spot and can't fix itself without +help. This section documents important fixes and things that can go wrong when +working with XBPS. + +## Section Contents + +- [Common Issues](./common-issues.md) +- [Static XBPS](./static.md) diff --git a/src/xbps/troubleshooting/static.md b/src/xbps/troubleshooting/static.md new file mode 100644 index 0000000..dc2db93 --- /dev/null +++ b/src/xbps/troubleshooting/static.md @@ -0,0 +1,35 @@ +# Static XBPS + +In rare cases, it is possible to break the system sufficiently that XBPS can no +longer function. This usually happens while trying to do unsupported things with +libc, but can also happen when an update contains a corrupt glibc archive or +otherwise fails to unpack and configure fully. + +Another issue that can present itself is in systems with a XBPS version before +`0.54` (released June 2019). These systems will be impossible to update from the +official repositories using the regular update procedure, due a change in the +compression format used for repository data, which was made in March 2020. + +In these cases it is possible to recover your system with a separate, statically +compiled copy of XBPS. + +## Obtaining static XBPS + +Statically compiled versions of XBPS are available on all mirrors in the +`static/` directory. The link below points to the static copies on the primary +mirror in the EU: + + + +Download and unpack the latest version, or the version that matches the broken +copy on your system (with a preference for the latest copy). + +## Using static XBPS + +The tools in the static set are identical to the normal ones found on most +systems. The only difference is that these tools are statically linked to the +musl C library, and should work on systems where nothing else does. On systems +that can no longer boot, it is recommended to chroot in using a EvolutionOS +installation medium and use the static tools from there, as it is unlikely that +even a shell will work correctly on those systems. When using static XBPS with a +glibc installation, the environment variable `XBPS_ARCH` needs to be set.