├── 01_intro_01_preface.md ├── 02_about_01_intro.md ├── 02_about_02_help.md ├── 03_installation_01_installation.md ├── 04_everyday-usage_01_intro.md ├── 04_everyday-usage_02_torbrowser.md ├── 04_everyday-usage_03_pdfs.md ├── 04_everyday-usage_04_coyim.md ├── 04_everyday-usage_05_ricochet.md ├── 04_everyday-usage_06_onionshare.md ├── 04_everyday-usage_07_subgraph_firewall.md ├── 05_features_and_advanced_usage_01_intro.md ├── 05_features_and_advanced_usage_02_oz.md ├── 05_features_and_advanced_usage_03_tor.md ├── 05_features_and_advanced_usage_04_metaproxy.md ├── 05_features_and_advanced_usage_05_roflcoptor.md ├── 05_features_and_advanced_usage_06_grsecurity.md ├── 05_features_and_advanced_usage_07_macouflage.md ├── 05_features_and_advanced_usage_08_usblockout.md ├── 05_features_and_advanced_usage_09_virtualmachines.md ├── 06_appendix_01_intro.md ├── 06_appendix_02_syscalls_01.md ├── 06_appendix_02_syscalls_02.md ├── Makefile ├── README.md ├── build ├── .gitignore ├── readability.txt ├── sgos_handbook.html ├── sgos_handbook.pdf ├── sgos_handbook.xml └── sgos_handbook_dev.xml ├── metadata.yaml ├── po ├── sgos_handbook.pot └── sgos_handbook_fixed.pot ├── scripts ├── po4a_fixup.awk └── syscall_table.awk ├── static ├── fonts │ ├── NotoSans-Bold.ttf │ ├── NotoSans-BoldItalic.ttf │ └── NotoSans-Regular.ttf ├── images │ ├── CoyIM_account_details_basic.png │ ├── CoyIM_configure_master_password.png │ ├── CoyIM_connected.png │ ├── CoyIM_encrypt_config.png │ ├── Gnome_Disks_dialog_format.png │ ├── Gnome_Disks_dialog_restore.png │ ├── Gnome_Disks_menu_format.png │ ├── Gnome_Disks_menu_restore.png │ ├── Gnome_Disks_select.png │ ├── OnionShare_TorBrowser.png │ ├── OnionShare_onionshare-gui.png │ ├── OnionShare_select_file.png │ ├── Oz_menu_addfiles_pdf.png │ ├── Oz_menu_addfiles_pdf_prompt.png │ ├── Ricochet_add_contact.png │ ├── Ricochet_chatting.png │ ├── Subgraph_Firewall_alert.png │ ├── Subgraph_Firewall_edit_rule.png │ ├── Subgraph_Firewall_menu.png │ ├── Subgraph_Firewall_options.png │ ├── Subgraph_Firewall_settings.png │ ├── oz_menu_addfiles_menu.png │ ├── oz_menu_addfiles_prompt.png │ ├── oz_menu_zebra.png │ ├── sgos.png │ ├── sgos_handbook_cover.png │ ├── subgraph_splash.png │ ├── virt-manager_00_firtlaunch_delete.png │ ├── virt-manager_00_firtlaunch_error.png │ ├── virt-manager_00_hypervisor_select.png │ ├── virt-manager_00_virtman_ready.png │ ├── virt-manager_01_browser.png │ ├── virt-manager_01_cpuram.png │ ├── virt-manager_01_createnew.png │ ├── virt-manager_01_diskimage.png │ ├── virt-manager_01_done.png │ └── virt-manager_01_name.png ├── sgos_handbook_cover.pdf └── sgos_handbook_cover.svg ├── subgraph-os-help.desktop └── templates ├── default.latex ├── sgos_handbook.css ├── sgos_handbook.latex ├── sgos_handbook_epub.css └── style.tex /01_intro_01_preface.md: -------------------------------------------------------------------------------- 1 | 2 | \newpage 3 | 4 | # Preface 5 | 6 | We have created this handbook as an instructional manual on how to use the 7 | Subgraph operating system. This handbook also introduces various security 8 | and privacy enhancing technologies that we have developed at Subgraph. 9 | 10 | We wrote this book for new users of Subgraph OS. Whether you are new to Linux 11 | or coming from another Linux-based operating system, we want to ease your 12 | transition to Subgraph OS. 13 | 14 | In the first section, we describe how to perform common tasks such as 15 | installing Subgraph OS and using the various applications that are included. 16 | Start here to get up and running with Subgraph OS as quickly as possible. 17 | 18 | The next section describes the various features of Subgraph OS that 19 | distinguish it from other operating systems. Users can refer to this section to 20 | learn the various security and privacy features. Advanced users will find this 21 | section useful for configuring operating system features and Subgraph 22 | applications. 23 | 24 | \newpage 25 | 26 | -------------------------------------------------------------------------------- /02_about_01_intro.md: -------------------------------------------------------------------------------- 1 | # Subgraph OS 2 | 3 | \newpage 4 | 5 | ## What is Subgraph OS? 6 | 7 | Subgraph OS is an *adversary resistant computing* platform. 8 | 9 | Subgraph OS empowers people to communicate, share, and collaborate without 10 | fear of surveillance and interference. We designed it so that our users can 11 | safely perform their day-to-day tasks securely and privately. 12 | 13 | In some ways, Subgraph OS is like other operating systems -- it is derived 14 | from Debian GNU/Linux. It provides the familiar GNOME desktop environment as 15 | its graphical user interface. Subgraph OS includes applications found in other 16 | Linux distributions. These similarities make Subgraph OS easy to adopt, 17 | especially for users with prior Linux experience. 18 | 19 | Subgraph OS also has key differences from conventional Linux operating systems. 20 | In particular: 21 | 22 | 1. Subgraph OS anonymizes Internet traffic by sending it through the Tor network 23 | 2. Security hardening makes Subgraph OS more resistant to security vulnerabilities 24 | 3. Subgraph runs many desktop applications in a security sandbox to limit their 25 | risk in case of compromise 26 | 27 | \newpage 28 | 29 | ## What do we mean by security and privacy? 30 | 31 | People attach different meanings to the words security and privacy. In computer 32 | security, a secure system is one that assures the `confidentiality, integrity, 33 | and availability` of information it stores, processes, or communicates. 34 | 35 | >`Confidentiality` assures that information is not revealed to anybody who is not authorized 36 | > 37 | >`Integrity` assures that information cannot be modified or tampered with by anybody who is not authorized 38 | > 39 | >`Availability` assures that information can be reliably accessed by those who are authorized 40 | 41 | Privacy is similar to confidentiality. Privacy also relies heavily on the 42 | integrity of communications. Our computers and other devices gather a great deal 43 | of information about our thoughts, our lives, and our social networks. They 44 | transmit this information over the Internet without our knowledge and consent. 45 | We have no way to trust the systems and networks that relay our communications 46 | over the Internet. 47 | 48 | We designed Subgraph OS with these concerns in mind. We did this because 49 | we believe people should be able to communicate with each other privately. We 50 | also believe that people should not be required to reveal information about 51 | themselves or their social network without explicit consent. 52 | 53 | ## What is adversary resistant computing? 54 | 55 | We designed Subgraph from the ground up to defend against threats to security 56 | and privacy. We aim to provide our users with a computing platform that is 57 | *adversary resistant*. 58 | 59 | We when use the term *adversary*, we are referring to an actual or hypothetical 60 | threat to the confidentiality, integrity, and availability of information. 61 | 62 | Hackers who exploit software vulnerabilities are a type of adversary. 63 | This is an actual and often active threat to security and privacy. 64 | 65 | Adversaries present passive or indirect threats as well. An adversary may be 66 | passively gathering network traffic to conduct surveillance on users. 67 | 68 | Lastly, adversaries may present theoretical or impractical threats. For 69 | example, a cryptography algorithm may have a theoretical weakness. At the time 70 | the weakness is discovered, the threat may not *practical* in the real world. 71 | As technology and attack methods improve, the weakness ceases to be 72 | theoretical and real world attacks emerge. 73 | 74 | We use the term *adversary* to cover all of the above possibilities. 75 | 76 | Secure systems should be resistant to all of these types of threats. 77 | 78 | While no computing platform can anticipate and defend against all possible 79 | threats by all possible adversaries, we aspire to make such attacks extremely 80 | difficult for adversaries. By making these attacks difficult, they also 81 | become more expensive for adversaries. Adversaries must bear the cost at scale 82 | if a large number of users deploy strong security and privacy defenses. Through 83 | Subgraph OS, we aim to make these defenses freely available and easy to deploy. 84 | 85 | Some of our users have critical security and privacy needs. Subgraph OS grants 86 | them strong security and privacy to conduct their activities safely. Casual 87 | users also gain the same security and privacy benefits without having to 88 | sacrifice usability and maintainability. 89 | 90 | This is *adversary resistant computing*. 91 | 92 | \newpage 93 | 94 | -------------------------------------------------------------------------------- /02_about_02_help.md: -------------------------------------------------------------------------------- 1 | ## Getting help with Subgraph OS 2 | 3 | We hope to address most concerns with this handbook. If you have questions that 4 | are not addressed in this handbook, you can contact us through other means. 5 | 6 | > **Contacting Subgraph** 7 | > 8 | > *Email*: Our email address is info \ subgraph.com 9 | > 10 | > *IRC*: You can join our IRC channel #subgraph on the OFTC network 11 | > 12 | > Our IRC channel is also available through webchat at: 13 | > 14 | > 15 | > 16 | > *Twitter*: Our Twitter is **@subgraph**, send us a message 17 | 18 | We are also involved in running the **Secure Desktops** mailing list. This 19 | discussion group covers the topic of **Secure Desktop** operating systems such 20 | as Subgraph OS, Qubes OS, and Tails. Developers from these projects participate 21 | in the mailing list. 22 | 23 | Further information about **Secure Desktops** can be found here: 24 | 25 | 26 | 27 | \newpage 28 | 29 | ### Reporting bugs 30 | 31 | If you find a bug in Subgraph OS, you can report it to us on Github. 32 | 33 | Our issue tracker for Subgraph OS is: 34 | 35 | 36 | 37 | You can also find our individual software repositories at: 38 | 39 | 40 | 41 | \newpage 42 | 43 | ### Getting the Subgraph OS Handbook 44 | 45 | Up-to-date versions of this handbook can be found on the following page: 46 | 47 | 48 | 49 | The PDF can be downloaded here: 50 | 51 | 52 | 53 | Subgraph OS will also include versions of this handbook in different formats. 54 | 55 | \newpage 56 | -------------------------------------------------------------------------------- /03_installation_01_installation.md: -------------------------------------------------------------------------------- 1 | # Installing Subgraph OS 2 | 3 | \newpage 4 | 5 | ## System requirements 6 | 7 | Subgraph OS runs on Intel 64-bit computers. These are the system 8 | requirements: 9 | 10 | * Intel 64-bit processor (Core2 Duo or later) 11 | * 2GB of RAM (4GB recommended) 12 | * At least 20GB of hard-disk space 13 | 14 | \newpage 15 | 16 | ## Downloading and verifying the Subgraph OS ISO 17 | 18 | Subgraph OS can be downloaded from our website: 19 | 20 | 21 | 22 | The Subgraph OS download page always has the most up-to-date download links and 23 | instructions. You can download the ISO directly from the website or over a Tor 24 | hidden service. 25 | 26 | You should always verify that the ISO you downloaded is the official version. 27 | To verify the ISO, we have included a checksum that is cryptographically signed 28 | by our developers. 29 | 30 | > *What is a checksum?* 31 | > 32 | > A checksum (or hash) is a string that uniquely identifies some piece of data 33 | > as being different from another piece of data. It is computed using a special 34 | > hash algorithm (SHA256 in our case). When data is passed to the hash 35 | > algorithm, the algorithm will return a shortened string (the checksum) that 36 | > uniquely identifies the data. Checksums are often used to ensure the `integrity` 37 | > of a file. `Integrity` in this case means that the file has not been corrupted 38 | > or tampered with during the download. 39 | > 40 | > *What is a cryptographic signature?* 41 | > 42 | > A cryptographic (or digital) signature is a method of authenticating a piece 43 | > of data. Data is signed with the `private` signing key of a person who has 44 | > created or is sending the data. The signature can then be verified by the 45 | > recipient using the `public` key of the sender. If the verification is 46 | > successful, this ensures that the data was created or sent by the person who 47 | > signed it and not somebody else. This `authenticates` the identify of the 48 | > creator or sender. 49 | > 50 | > *Why do we cryptographically sign the checksum?* 51 | > 52 | > The checksum is used to verify the `integrity` the ISO you have downloaded. 53 | > However, how do you verify that the checksum on our website was provided by 54 | > us? By cryptographically signing the checksum with our `private` key, you can 55 | > verify the `authenticity` of the checksum. 56 | 57 | ### Verifying the ISO on a Linux computer 58 | 59 | To verify the ISO on a Linux computer, you will need to download the ISO, SHA256 60 | checksum, and the signature for the checksum. 61 | 62 | The first step is to download our public key, Our public key can be downloaded 63 | with the following command: 64 | 65 | ```{.bash} 66 | $ gpg --recv-key B55E70A95AC79474504C30D0DA11364B4760E444 67 | ``` 68 | 69 | The second step is to verify the `authenticity` of the signature for the 70 | checksum. Run the following command to verify the signature (note: replace the 71 | filenames with the names of the files you downloaded): 72 | 73 | ```{.bash} 74 | $ gpg --verify subgraph-os-alpha_2016-06-16_2.iso.sha256.sig \ 75 | subgraph-os-alpha_2016-06-16_2.iso.sha256 76 | ``` 77 | 78 | After running this command, you should see a `Good Signature` message. If you 79 | have seen this message then you can proceed to the next step. 80 | 81 | The third step is to verify the `integrity` of the ISO using the SHA256 checksum. 82 | Run the following command to verify the checksum (note: replace the filenames with the 83 | names of the files you downloaded): 84 | 85 | ```{.bash} 86 | $ sha256sum -c subgraph-os-alpha_2016-06-16_2.iso.sha256 87 | ``` 88 | 89 | After running the command, you should see: 90 | 91 | ``` 92 | subgraph-os-alpha_2016-06-16_2.iso: OK 93 | ``` 94 | 95 | Congratulations, you have now downloaded and verified the Subgraph OS ISO. You 96 | are now ready to try it out! 97 | 98 | \newpage 99 | 100 | ## Installing from a USB drive on a Linux computer 101 | 102 | This section describes how to create a USB installer using Linux. One of these 103 | methods will work on any Linux computer (even on Subgraph OS). To create an 104 | installer you will need a USB drive with a capacity a 2GB or more. 105 | 106 | ### Creating a USB installer using Gnome Disks 107 | 108 | If you have a Linux computer that is running the Gnome Desktop, you can use the 109 | **Gnome Disks** application to create a USB installer. 110 | 111 | The following steps show how to make a USB installer using **Gnome Disks**: 112 | 113 | 1. Insert a USB drive into your Linux computer 114 | 115 | 2. Open the **Gnome Disks** application 116 | 117 | 3. Select your USB drive 118 | 119 | ![Gnome Disks - select USB drive](static/images/Gnome_Disks_select.png) 120 | 121 | \newpage 122 | 123 | 4. Select the **Format Disk** option in the top right corner of **Gnome Disks** 124 | 125 | ![Gnome Disks - Format Disks... option](static/images/Gnome_Disks_menu_format.png) 126 | 127 | \newpage 128 | 129 | 5. *Format* the USB drive 130 | 131 | ![Gnome Disks - Format dialog](static/images/Gnome_Disks_dialog_format.png) 132 | 133 | \newpage 134 | 135 | 6. Select the **Restore Disk Image** option in the top right corner of **Gnome 136 | Disks** 137 | 138 | ![Gnome Disks - Restore Disk Image... option](static/images/Gnome_Disks_menu_restore.png) 139 | 140 | \newpage 141 | 142 | 7. Choose the ISO file you want to *restore* (copy) to the USB drive 143 | 144 | 8. *Restore* the ISO to the USB drive 145 | 146 | ![Gnome Disks - Restore dialog](static/images/Gnome_Disks_dialog_restore.png) 147 | 148 | \newpage 149 | 150 | It should take a few minutes to copy the ISO to the USB drive. 151 | 152 | \newpage 153 | 154 | ### Creating a USB installer using dd 155 | 156 | If your Linux computer is not running Gnome Desktop or you want to create the 157 | installer from the command-line, you can use the **dd** utility. 158 | 159 | The following steps show how to make a USB installer using **dd**: 160 | 161 | 1. Insert a USB drive into your computer 162 | 163 | 2. Open a terminal and run the following command to identify the name of the USB 164 | drive: 165 | ```{.bash} 166 | $ lsblk 167 | ``` 168 | **NOTE**: You should see a name such as **/dev/sdx** for your drive, for 169 | example: **/dev/sdb**. It is important to use only the name without the 170 | partition number. If you see something like **/dev/sdb1**, you can omit 171 | the **1** at the end. The **dd** command uses the name without the partition 172 | number. 173 | 174 | 3. In the same terminal, run the following command: 175 | ```{.bash} 176 | $ dd bs=4M if=subgraph-os-alpha_2016-06-16_2.iso of=/dev/sdx \ 177 | status=progress && sync 178 | ``` 179 | **NOTE**: Replace the path of the ISO with the path of the ISO you have 180 | downloaded and verified. Replace **/dev/sdx** with the name of your USB 181 | drive, for example: **/dev/sdb**. 182 | 183 | Copying the ISO to the USB drive should take a few minutes. 184 | 185 | \newpage 186 | 187 | ## Booting from a USB drive (Live mode) 188 | 189 | Subgraph OS also features a 'live' mode. Subgraph OS live mode runs in memory, 190 | directly from the USB drive. While running in live mode, nothing 191 | will be saved to your hard-drive. When the live session ends, any data created 192 | during your session will disappear, leaving no traces behind on the hard-disk. 193 | \ 194 | \ 195 | People normally run in live mode for the following reasons: 196 | 197 | 1. They want to demo Subgraph OS 198 | 2. They want to test Subgraph OS with their particular hardware 199 | 3. They want to perform certain tasks with extra security and privacy but 200 | do not want a permanent installation of Subgraph OS 201 | 202 | \newpage 203 | 204 | When the Subgraph OS ISO starts, you will be presented with different options. 205 | To start the live mode, select `Live (amd64)`. 206 | 207 | ![Subgraph OS boot screen](static/images/subgraph_splash.png) 208 | 209 | Please note that the user password on the live image is: *live*. 210 | 211 | \newpage 212 | 213 | -------------------------------------------------------------------------------- /04_everyday-usage_01_intro.md: -------------------------------------------------------------------------------- 1 | # Everyday usage 2 | 3 | Subgraph OS comes with a number of applications that may already be familiar. 4 | We have also added newer alternatives that may be less familiar. This chapter 5 | shows you how to use these applications to perform everyday tasks. 6 | 7 | Subgraph OS is also unique because the applications we have included are run 8 | inside of a security sandbox. We call this sandbox **Oz**. **Oz** helps protect 9 | the operating system and your personal files in case an application is 10 | compromised by a security vulnerability. 11 | 12 | Each application described in this chapter runs inside an **Oz** sandbox. This 13 | means that they can only access the files and directories that they need to. 14 | Each of the applications is isolated from each other. They are also isolated 15 | from the system itself. Because the applications are isolated, they cannot 16 | access common directories such as `Pictures` or `Downloads` in the usual way. 17 | This chapter shows you how to manage your files in **Oz**, with some examples 18 | for each application. 19 | 20 | \newpage 21 | 22 | -------------------------------------------------------------------------------- /04_everyday-usage_02_torbrowser.md: -------------------------------------------------------------------------------- 1 | ## Browsing the Web with Tor Browser 2 | 3 | Tor Browser is the default web browser of Subgraph OS. It has a number of 4 | security and privacy advantages over other browsers. 5 | 6 | The security and privacy features include: 7 | 8 | * Anti-fingerprinting countermeasures to prevent websites from identifying 9 | individual users by their browser fingerprint 10 | * A security slider that lets users disable browser features that may pose 11 | security and privacy risks 12 | 13 | The Tor Browser runs inside a security sandbox, managed by Subgraph **Oz**. Web 14 | browsers represent some of the most complex software available. With complexity 15 | comes increased risk to security and privacy. This is what we call the `attack 16 | surface` of an application. Tor Browser is no different than other browsers in 17 | that it has a lot of attack surface. A successful compromise of Tor Browser 18 | could let an attacker gain access to things such as SSH keys, GPG encryption 19 | keys, personal files, email, etc. Our security sandbox technology helps to 20 | mitigate these risks. 21 | 22 | ### Configuring the Tor Browser security slider 23 | 24 | The Tor Browser includes a `security slider` that lets users choose the security 25 | and privacy features they want to enable. If they enable all of the security and 26 | privacy settings, some websites may be slower or may not work as expected. 27 | However, the security slider lets them instantly lower the settings if they need 28 | a particular website to work better. 29 | 30 | We recommend setting the security slider to Medium-High or High. For websites 31 | you trust, you can lower the settings to make the website perform better. 32 | 33 | We advise against lowering the security slider for any websites that are not 34 | accessed over HTTPS. HTTPS helps to make sure that the traffic between the Tor 35 | Browser and the website has not been tampered with. This is what we refer to 36 | as the 'integrity' security property. If you cannot verify the integrity of 37 | the traffic originating from a website by using HTTPS, it may be dangerous to 38 | visit the website using lowered security and privacy settings. 39 | 40 | \newpage 41 | 42 | ### Downloading and saving files in the Tor Browser 43 | 44 | The Tor Browser runs inside of **Oz**, our application sandbox. When files are 45 | downloaded by a sandboxed application such as the Tor Browser, they are saved 46 | within the sandbox. When you close the Tor Browser, **Oz** will cleanup the 47 | sandbox, causing files saved in the sandbox to be destroyed. 48 | 49 | To allow the Tor Browser to download that can persist after the application is 50 | closed, **Oz** makes a special exception. This special exception is a `shared 51 | directory` where files can be saved and retrieved later, without being destroyed 52 | when Tor Browser is closed. `Shared directory`, in this case, means a directory 53 | that is shared inside and outside of the **Oz** sandbox. **Oz** sets up the the 54 | following shared directory for saving downloaded files: 55 | ``` 56 | ~/Downloads/TorBrowser 57 | 58 | ``` 59 | 60 | The shared directory name may be localized depending on the language settings 61 | on your computer. In the case of French, the shared directory would be: 62 | ``` 63 | ~/Téléchargements/TorBrowser 64 | ``` 65 | 66 | Files downloaded to the shared directory will persist after closing the 67 | Tor Browser. 68 | 69 | ### Uploading files in the Tor Browser 70 | 71 | When the Tor Browser starts, the **Oz** sandbox limits its access to files and 72 | directories on the computer. For example, a photo from the `Pictures` directory 73 | will not be visible in the sandbox by default. If you want to upload a photo 74 | from this directory, you must use the *Oz menu* to add it to the Tor Browser 75 | sandbox. The **Oz** menu is denoted by the little zebra icon at the top-right 76 | corner of the screen. 77 | 78 | > ![Oz menu - icon](static/images/oz_menu_zebra.png){#id .class width=60 height=60px} 79 | > The following actions may be performed using the *Oz menu*: 80 | > 81 | > - Add files to sandbox 82 | > 83 | > - Open terminal in sandbox 84 | > 85 | > - Shutdown sandbox 86 | 87 | \clearpage 88 | 89 | Click on the little zebra and then click `Add file...`. 90 | 91 | ![Oz menu - Add file](static/images/oz_menu_addfiles_menu.png) 92 | 93 | You may add more than one file at a time. You may 94 | also choose to make these files `read-only`, meaning that they can only be 95 | read and not written to while in the sandbox. 96 | 97 | ![Oz menu - Select files or directories](static/images/oz_menu_addfiles_prompt.png) 98 | 99 | \clearpage 100 | 101 | Once the file(s) you want to upload are added to the Tor Browser sandbox, you 102 | may proceed to upload them normally. 103 | 104 | 105 | -------------------------------------------------------------------------------- /04_everyday-usage_03_pdfs.md: -------------------------------------------------------------------------------- 1 | ## Viewing PDFs 2 | 3 | PDFs present security and privacy risks to users. Subgraph OS sandboxes 4 | PDFs in a safe environment, minimizing those risks. 5 | 6 | PDFs are affected by the following security and privacy risks: 7 | 8 | 1. PDF readers have security vulnerabilities that can be exploited by opening a 9 | malicious PDF 10 | 2. PDFs may make outgoing connections to the Internet, compromising the user's 11 | privacy either by sending personally identifiable information or network 12 | traffic that can be correlated with the user's other activities 13 | 14 | 15 | To address the first problem, the security hardening in Subgraph OS makes it 16 | much more difficult to exploit security vulnerabilities in the PDF reader 17 | (**Evince**). 18 | 19 | If a malicious PDF bypasses the security hardening in Subgraph OS, it 20 | compromises the PDF reader. However, because **Evince** runs inside of a sandbox, 21 | this limits what an attacker can do. The sandbox in Subgraph OS is called 22 | **Oz**. 23 | 24 | The sandbox prevents **Evince** from accessing sensitive files on 25 | the computer, such as your encryption keys, email, personal documents, etc. 26 | **Evince** only requires access to the PDF(s) it is reading and some other files 27 | it needs to operate normally. 28 | 29 | **Oz** also prevents **Evince** from connecting to the Internet. This can prevent 30 | malicious code from communicating with the outside world. Privacy is also 31 | preserved since **Evince** cannot send data that can *fingerprint* the user. 32 | 33 | Lastly, the sandbox limits other types of actions through a Linux feature called 34 | *seccomp*. 35 | 36 | > *What is a system call?* 37 | > 38 | > System calls provide a way for applications, which run in *user-space*, to 39 | > ask the kernel (running in *kernel-space*) to do things such as read and write 40 | > files, communicate over the network, etc. 41 | > 42 | > When a *user-space* application makes a system call to do something such as 43 | > open a file, the kernel must perform a number of low-level actions. The 44 | > kernel may be responsible for the file system implementation, authorizing the 45 | > application to access the file, reading the file contents from the hard-drive, 46 | > etc. The kernel must run with *elevated privileges* in relation to the 47 | > application to perform these low-level actions. System calls let applications 48 | > cross the boundary between *user-space* and *kernel-space* without requiring 49 | > the application to run with kernel-level privileges. 50 | > 51 | > System calls are critical to security because they provide an interface for 52 | > lower-privileged applications to send input to the kernel. 53 | > 54 | > See the Appendix for a complete list of system calls in Subgraph OS. 55 | 56 | Sandboxed applications in Subgraph OS include a set of policies called a 57 | *seccomp whitelist*. If an attacker compromises an application, this security 58 | feature can prevent them from gaining elevated privileges on your computer. 59 | 60 | > *What is seccomp?* 61 | > 62 | > *Seccomp* is a security feature of Linux that can restrict access to 63 | > system calls. If an application tries to run one of the system calls 64 | > restricted by *seccomp*, it will be killed instead of allowing the 65 | > system call to run. This can prevent privilege escalation in case malicious 66 | > code tries to exploit kernel vulnerabilities through system calls. System 67 | > calls are often used as a *payload* in malicious code to do some things as 68 | > read files or open network connections. *Seccomp* can also prevent *payloads* 69 | > from running if they use system calls are that blocked by the policy. 70 | > 71 | > *What is a seccomp whitelist?* 72 | > 73 | > A *seccomp whitelist* is a list of allowed system calls. If the application 74 | > tries to call any system call *not* on this list, it is killed by *seccomp*. 75 | > 76 | > *What is a seccomp blacklist?* 77 | > 78 | > A *seccomp blacklist* is a list of forbidden system calls. If the application 79 | > tries to call any system call *on* this list, it will be killed by *seccomp*. 80 | > This is in contract to the whitelist, which blocks the calls *not* on the 81 | > list. 82 | > 83 | > The **Oz** sandbox in Subgraph OS supports both *seccomp whitelists* and 84 | > *seccomp blacklists*. 85 | 86 | \newpage 87 | 88 | ### Opening PDFs with Evince in the file explorer 89 | 90 | 91 | Clicking on a PDF in the file explorer will automatically open the PDF using 92 | **Evince** in the **Oz** sandbox. 93 | 94 | ### Adding PDFs to Evince from the Oz menu 95 | 96 | If the PDF reader is already open, the PDF can be added to the sandbox by 97 | clicking on *Add file...* option of the *Oz menu* for **Evince**. 98 | 99 | ![Oz menu - Add file](static/images/Oz_menu_addfiles_pdf.png) 100 | 101 | \newpage 102 | 103 | You may add multiple files. You can also make these files *read-only*, meaning 104 | that they cannot be modified in the sandbox. 105 | 106 | ![Oz menu - Select files or directories](static/images/Oz_menu_addfiles_pdf_prompt.png) 107 | 108 | \clearpage 109 | 110 | ### Opening PDFs from the command-line terminal 111 | 112 | PDFs may also be opened from the terminal. 113 | 114 | For example, to open this handbook using **Evince** in the terminal, run the 115 | following command: 116 | 117 | ```{.bash} 118 | $ evince sgos_handbook.pdf 119 | ``` 120 | 121 | After running the command, you will see the following message: 122 | ``` 123 | ok received 124 | ``` 125 | 126 | This message indicates that **Oz** has received the request to launch *Evince*. 127 | 128 | You may be surprised that opening the PDF from the terminal also opens it in the 129 | sandbox. This is because **Oz** re-routes the commands so that they run in the 130 | sandbox. For any application that runs in **Oz**, you may launch it from the 131 | desktop *or* the command-line terminal. 132 | 133 | \newpage 134 | 135 | -------------------------------------------------------------------------------- /04_everyday-usage_04_coyim.md: -------------------------------------------------------------------------------- 1 | ## Chatting with CoyIM 2 | 3 | **CoyIM** is one of the instant messaging clients in Subgraph OS. **CoyIM** 4 | supports the *Jabber/XMPP* instant messaging protocol. All chats are end-to-end 5 | encrypted using *OTR* (Off-the-Record) Messaging. 6 | 7 | **CoyIM** is developed by the *ThoughtWorks STRIKE* team as a more secure 8 | alternative to chat software such as **Pidgin** and **Adium**. 9 | 10 | More information about **CoyIM** can be found here: 11 | 12 | 13 | 14 | \newpage 15 | 16 | ### Adding an XMPP account to CoyIM 17 | 18 | When **CoyIM** opens for the first time, it asks you if you want to encrypt your 19 | configuration file. We recommend that you encrypt your configuration. 20 | 21 | ![CoyIM - Encrypt configuration file](static/images/CoyIM_encrypt_config.png) 22 | 23 | If you have decided to encrypt your configuration file, you will be prompted 24 | to configure the master password that will be used to encrypt your 25 | configuration file. You will need to re-enter this password each time you 26 | use **CoyIM**, so choose something strong but memorable! 27 | 28 | ![CoyIM - Configure master password](static/images/CoyIM_configure_master_password.png) 29 | 30 | To begin using **CoyIM**, you must first add an existing account from an *XMPP* 31 | network. 32 | 33 | ![CoyIM - Account details: basic configuration](static/images/CoyIM_account_details_basic.png) 34 | 35 | Once you had added your account details, you can connect your account. If 36 | you have successfully connected to the chat network, a *green* dot will appear 37 | to the left of your username. 38 | 39 | ![CoyIM - Successful connection](static/images/CoyIM_connected.png) 40 | 41 | \clearpage 42 | 43 | -------------------------------------------------------------------------------- /04_everyday-usage_05_ricochet.md: -------------------------------------------------------------------------------- 1 | ## Chatting over Tor with Ricochet 2 | 3 | **Ricochet** is an anonymous peer-to-peer instant messaging application. 4 | **Ricochet** lets people chat directly with each other over Tor. Unlike other 5 | chat services, no intermediate servers are required. This means that 6 | **Ricochet** does not store your contact lists and chat histories on a server 7 | somewhere in the cloud. 8 | 9 | **Ricochet** is built on top of Tor hidden services. Tor hidden services provide 10 | anonymity and end-to-end encryption. This enables people to have conversations 11 | that are private and secure. 12 | 13 | > *What is a Tor hidden service?* 14 | > 15 | > Tor hidden services provides a means of hosting services on the Tor network. 16 | > Any type of network service may be hosted as a hidden service (such as web 17 | > servers, file shares, and instant messaging servers). 18 | > 19 | > Instead of using an IP address or domain name, Tor hidden services are 20 | > accessed by their *.onion* address. The *.onion* address is an automatically 21 | > generated name that is derived from the public key of the hidden service. 22 | > 23 | > *.onion* addresses are only accessible over Tor. **Tor Browser** is one way to 24 | > access *.onion* addresses. In Subgraph OS, any application can access *.onion* 25 | > addresses because all applications are routed through Tor. 26 | > 27 | > Tor hidden services provide privacy and anonymity for both the server and the 28 | > client. Tor hidden services have the following benefits over 29 | > regular network services: 30 | > 31 | > 1. Neither the client nor the server need to know the network location (IP 32 | > address) of each other. Tor routes traffic through a series of rendezvous 33 | > points that hide the client IP address from the server. The server's 34 | > network location (IP address) is also hidden from the client, who connects 35 | > to the *.onion* address of the server. 36 | > 2. All traffic between the client and server is end-to-end encrypted. Traffic 37 | > never leaves the Tor network, meaning that it is only decrypted on either 38 | > end of the transaction. When Tor is used to connect to the regular 39 | > Internet, traffic is only encrypted until the *exit-node*. Without using 40 | > another layer of encryption such as HTTPS, exit nodes can observe traffic. 41 | > Tor hidden services are not affected by this limitation. 42 | > 43 | > More information about the hidden services protocol can be found here: 44 | > 45 | > 46 | 47 | In **Ricochet**, each user has a *contact ID* that maps to a Tor hidden service 48 | that is hosted on their computer. The application manages all of the plumbing of 49 | creating the hidden service on your computer and communicating with your 50 | contacts via their hidden services. 51 | 52 | More information about Ricochet can be found on the following pages: 53 | 54 | * 55 | * 56 | 57 | \newpage 58 | 59 | ### Chatting in Ricochet 60 | 61 | **Ricochet** is similar to other instant messaging clients. The application 62 | shows the contacts that are online. You can open chat sessions with your 63 | contacts and switch between those sessions like in any other instant messager. 64 | 65 | ![Ricochet - Chatting](static/images/Ricochet_chatting.png) 66 | 67 | \newpage 68 | 69 | ### Adding a contact in Ricochet 70 | 71 | If you know the *contact ID* of another user, you can add them as a contact. To 72 | add a contact, click the **+** button in the top-left corner of the application 73 | window. 74 | 75 | ![Ricochet - Adding a contact](static/images/Ricochet_add_contact.png) 76 | 77 | > **Ricochet contact options** 78 | > 79 | > *ID*: The *contact ID* of the contact you want to add 80 | > 81 | > *Name*: A nickname for the contact you want to add 82 | > 83 | > *Message*: The message you want to send when adding the contact 84 | 85 | \newpage 86 | 87 | -------------------------------------------------------------------------------- /04_everyday-usage_06_onionshare.md: -------------------------------------------------------------------------------- 1 | ## Sharing files with OnionShare 2 | 3 | **OnionShare** is a anonymous, peer-to-peer file sharing application. It lets people 4 | share files of any size private and securely. 5 | 6 | **OnionShare** is built on top of Tor hidden services. There are a number of 7 | security and privacy advantages to sharing files over Tor hidden services using 8 | **OnionShare**. 9 | 10 | 1. Tor hidden service connections are end-to-end encrypted, meaning that the 11 | file transfer is encrypted at every point between the client and server. 12 | 2. Tor hidden service connections are anonymous. File transfers can occur 13 | without the either the client or the server knowing the IP address of each 14 | other. The server is hidden behind an *.onion* address on the Tor network. 15 | The client is hidden because it connects to the hidden service through 16 | different rendezvous points. 17 | 3. *OnionShare* file shares are designed to be short-lived. They can shut down 18 | after the file transfer occurs, meaning the server stops listening and the 19 | *.onion* address disappears from the Tor network. 20 | 21 | Subgraph OS enhances the security of **OnionShare** by sandboxing it with 22 | **Oz**. File shares exist in their own sandbox, without access to other 23 | sensitive files on the computer. If **OnionShare** is affected by a security 24 | vulnerability, running it **Oz** limits the consequences of the vulnerability. 25 | 26 | When a user shares files, **OnionShare** starts a hidden service with its own 27 | *.onion* address. The user then sends the *.onion* address to the people they 28 | wish to share files with. The *.onion* address should be sent over a 29 | *secure communication channel*. This is important to prevent unwanted parties 30 | from accessing your shared files. Once files are shared, people with the 31 | *.onion address* can download the files using the **Tor Browser**. 32 | 33 | > *What is a secure communication channel?* 34 | > 35 | > A communication channel is secure if people can communicate with some 36 | > expectation that their conversation cannot be intercepted or tampered with. 37 | > Ideally, all communications should be encrypted along with their metadata. 38 | > Metadata includes things such as the time, date, and frequency of the 39 | > conversations. It can also include the identities and location of the people 40 | > who are communicating. Even without the content of a conversation, metadata 41 | > can reveal a lot about the nature of the communication. 42 | > 43 | > Establishing *truly* secure communications channels is difficult. Many 44 | > communications tools rely on third-parties, making them privy to 45 | > communications metadata. This may include the third-party servers themselves 46 | > or intermediary servers that pass on the communications. Communications, 47 | > even encrypted ones, often leak metadata as they travel to their final 48 | > destination. 49 | > 50 | > Subgraph OS includes applications to help our users communicate over secure 51 | > channels. These examples are ranked according to the amount of metadata they 52 | > reveal: 53 | > 54 | > * Ricochet instant messager (uses Tor hidden services for anonymity and 55 | > end-to-end encryption, no metadata, no third-party servers required) 56 | > * CoyIM instant messager (uses the XMPP protocol, some metadata, requires 57 | > third-party servers) 58 | > * Encrypted email using Icedove/Torbirdy (uses the SMTP protocol, lots of 59 | > metadata, requires third-party servers) 60 | 61 | More information about **OnionShare** is on the following website: 62 | 63 | 64 | 65 | \newpage 66 | 67 | ### Share via OnionShare 68 | 69 | **OnionShare** is integrated into the file explorer of Subgraph OS. To share a file, 70 | *right-click* on the file and select *Share via OnionShare*. 71 | 72 | ![OnionShare - Share via OnionShare](static/images/OnionShare_select_file.png) 73 | 74 | \newpage 75 | 76 | Selecting *Share via OnionShare* will start **OnionShare** and open the 77 | **onionshare-gui**. It may take a few seconds for OnionShare to create the 78 | hidden service. The status indicator will turn *green* when it is ready. 79 | 80 | ![OnionShare - onionshare-gui](static/images/OnionShare_onionshare-gui.png) 81 | 82 | **onionshare-gui** includes the following options to manage shared files: 83 | 84 | * Add Files 85 | * Add Folder 86 | * Delete (Files and Folders) 87 | * Stop Sharing (all files and folders, this closes **OnionShare**) 88 | 89 | OnionShare runs inside of the **Oz** sandbox. To add files and folders after 90 | OnionShare has started, they must be added through the **Oz** menu at the top 91 | right corner of the desktop. See the section on *Viewing PDFs* for further 92 | information on adding files and folders to an application in the **Oz** sandbox. 93 | 94 | The URL for the hidden service (the *.onion* address) is provided along with a 95 | button to *Copy URL* to the clipboard. This URL should be sent over a 96 | *secure communication channel* to the people you want to share files 97 | with. 98 | 99 | The *Stop sharing automatically* checkbox determines whether **OnionShare** will 100 | close automatically after the file is downloaded by a user. Un-check this option 101 | if you are sharing files with multiple users. 102 | 103 | ### Download files from OnionShare 104 | 105 | **OnionShare** runs as a Tor hidden service. To download files over 106 | **OnionShare**, you can use the **Tor Browser**. Paste the *.onion* 107 | address for the file share into the address bar of **Tor Browser**. This will 108 | open the web interface for **OnionShare**. 109 | 110 | ![OnionShare - web interface in Tor Browser](static/images/OnionShare_TorBrowser.png) 111 | 112 | **NOTE**: In this screenshot, **OnionShare** (the server) and **Tor Browser** 113 | (the client) are both running on the same computer. Because the **OnionShare** 114 | server is only accessible over a Tor hidden service, **Tor Browser** connects 115 | to the file share over Tor. This is the case even if they are running on the 116 | same computer. Of course, normally the server and the client would run on 117 | different computers 118 | 119 | \newpage 120 | 121 | -------------------------------------------------------------------------------- /04_everyday-usage_07_subgraph_firewall.md: -------------------------------------------------------------------------------- 1 | ## Monitoring outgoing connections with Subgraph Firewall 2 | 3 | **Subgraph Firewall** is an *application firewall* that is included in Subgraph 4 | OS. While most firewalls are designed to handle incoming network communications, 5 | an *application firewall* can handle outgoing network communications. **Subgraph 6 | Firewall** can apply policies to outgoing connections on a per-application 7 | basis. 8 | 9 | *Application firewalls* are useful for monitoring unexpected connections from 10 | applications. For example, some applications may *phone home* to the vendor's 11 | website. Often this activity is legitimate (non-malicious) but it still may 12 | violate the user's privacy or expectations of how the software operates. 13 | Subgraph Firewall gives users the choice to allow or deny these connections. 14 | 15 | Malicious code may also *phone home* to a website or server that is operated by 16 | the hacker or malicious code author. Subgraph Firewall can also alert the user 17 | of these connections so that they can be denied. 18 | 19 | *Application firewalls* cannot prevent all malicious code from connecting to the 20 | Internet. Sophisticated malicious code can subvert the *allowed* connections to 21 | bypass the firewall. However, the firewall may alert the user of connection 22 | attempts by less sophisticated malicious code. 23 | 24 | Our *application firewall* makes Subgraph OS unique. It is not found in other 25 | Linux distributions. Normally, applications will make outgoing network 26 | connections without the knowledge or consent of the user. Subgraph OS helps 27 | mitigate these security and privacy risks by making users aware and giving them 28 | the power to decide how applications connect to the Internet. 29 | 30 | ### Allowing or denying connections in Subgraph Firewall 31 | 32 | When Subgraph Firewall sees a connection it does not have a policy for, it 33 | prompts the user to *allow* or *deny* the connection. The prompt includes 34 | options to define the duration of the policy and the scope. By scope, we mean 35 | apply the policy for the application to a specific destination or to any 36 | connection made by the application. 37 | 38 | 39 | \clearpage 40 | 41 | > While developing Subgraph Firewall, we noticed some unusual behavior from 42 | > **Gnome Calculator**. We didn't expect that a calculator would need to connect 43 | > to the Internet and so we were surprised to see a prompt from **Subgraph 44 | > Firewall**. **Gnome Calculator** connects to various bank websites to fetch 45 | > the exchange rates for currency conversions. 46 | > 47 | > This type of unexpected behavior is one of the reasons we created **Subgraph 48 | > Firewall**. **Gnome Calculator** doesn't give the user the choice to fetch the 49 | > exchange rates. **Subgraph Firewall** puts that choice back in the hands of 50 | > the user. 51 | 52 | ![Subgraph Firewall - allow/deny prompt](static/images/Subgraph_Firewall_alert.png) 53 | 54 | > **Subgraph Firewall Allow/Deny prompt options** 55 | > 56 | > At the top of the prompt is the name of the application making the connection 57 | > as well the destination hostname and port. 58 | > 59 | > *IP address*: The destination IP address 60 | > 61 | > *Path*: The path to the application that is making the connection 62 | > 63 | > *Process ID*: The process ID of the application that is making the connection 64 | > 65 | > *User*: The user who started the application that is making the connection 66 | > 67 | > *Allow/Deny* duration 68 | > 69 | > *Forever*: *Allow* or *Deny* the connection forever (this can be changed 70 | > afterwards in the Subgraph Firewall settings) 71 | > 72 | > *Session*: *Allow* or *Deny* the connection until logging out of the desktop 73 | > session 74 | > 75 | > *Once*: *Allow* or *Deny* the connection once (the prompt will re-appear if 76 | > the application attempts the connection again) 77 | > 78 | > *Allow/Deny* scope 79 | > 80 | > *Only hostname on port*: Allow/Deny the connection for this application 81 | > only for the *hostname* and *port* listed at the top of the firewall prompt 82 | > 83 | > *Any Connection*: Allow/Deny any connection made by the application 84 | 85 | \newpage 86 | 87 | ### Configuring firewall rules in Subgraph Firewall 88 | 89 | To configure the firewall rules, select the **Firewall -> Firewall Settings** 90 | option from the *Gnome User Menu* at the top right corner of the desktop. 91 | 92 | ![Gnome User Menu - Firewall -> Firewall Settings](static/images/Subgraph_Firewall_menu.png) 93 | 94 | \newpage 95 | 96 | This will open the **Firewall Settings** configuration window. 97 | 98 | ![Subgraph Firewall Settings](static/images/Subgraph_Firewall_settings.png) 99 | 100 | \newpage 101 | 102 | The configuration window shows all of the existing rules. 103 | 104 | Each rule has the following columns: 105 | 106 | * Application name 107 | * A policy setting of *ALLOW* or *DENY* 108 | * The scope of the policy 109 | 110 | The last two options are to *Edit* or *Delete* a firewall rule. 111 | 112 | If you click the *Edit* button (the button with the wrench), you will be 113 | prompted to edit the *Allow/Deny* policy and its scope. 114 | 115 | ![Subgraph Firewall Settings - Edit Rule](static/images/Subgraph_Firewall_edit_rule.png) 116 | 117 | \newpage 118 | 119 | The *Options* tab of the **Firewall Settings** window lets you configure general 120 | options for **Subgraph Firewall**. 121 | 122 | ![Subgraph Firewall Settings -Options](static/images/Subgraph_Firewall_options.png) 123 | 124 | \clearpage 125 | 126 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_01_intro.md: -------------------------------------------------------------------------------- 1 | # Features and advanced usage 2 | 3 | This chapter describes the unique features of Subgraph OS. These are features 4 | that distinguish it from other operating systems. This is where you can find 5 | more information about the design of Subgraph OS. 6 | 7 | As an *adversary resistant computing* platform, Subgraph OS is designed to 8 | resist threats to security and privacy. This chapter includes more information 9 | about how our design addresses these threats. We also provide links to external 10 | sources where more in-depth technical information is available. 11 | 12 | This chapter also provides documentation for some advanced use-cases in Subgraph 13 | OS. This content is more technical than previous chapters in the Subgraph OS 14 | Handbook. It contains *how-tos* and reference materials intended for users who 15 | are comfortable running commands in the terminal and editing configuring files. 16 | 17 | \newpage 18 | 19 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_02_oz.md: -------------------------------------------------------------------------------- 1 | ## Sandboxing applications with Subgraph OZ 2 | 3 | Subgraph OS runs desktop applications inside of our security sandbox (**OZ**). 4 | The security sandbox is an additional layer of security, above and beyond the 5 | othersecurity features of Subgraph OS. Subgraph OS is hardened to make it very 6 | difficult for an attacker to compromise applications. However, it is impossible 7 | to prevent every vulnerability. If an attacker compromises an application, 8 | **OZ** can help to protect the computer and the user's sensitive files against 9 | further compromise. 10 | 11 | **OZ** can provide the following protections to sandboxed applications: 12 | 13 | * Restrict the files that the application has access to 14 | * Restrict network access 15 | * Restrict audio playback 16 | * Restrict the system calls the application can make (using **seccomp**) 17 | * Restrict malicious interactions between X11 applications (using **xpra**) 18 | 19 | Each sandboxed application has its own policies to restrict its capabilities. 20 | 21 | The following table shows some of the sandbox policies in Subgraph OS: 22 | 23 | Application Category Network? Audio? 24 | ----------- -------- -------- ------ 25 | Tor Browser Browser Proxy port Yes 26 | Icedove Email client Proxy port No 27 | CoyIM Instant messager Proxy port No 28 | Ricochet Instant messager Proxy port No 29 | Hexchat IRC client Proxy port No 30 | OnionShare File sharing Proxy port No 31 | VLC Video player No Yes 32 | LibreOffice Office suite No No 33 | Evince PDF reader No No 34 | Eog Image Viewer No No 35 | 36 | \newpage 37 | 38 | **OZ** also sandboxes desktop applications from each other. Normally, 39 | applications running under the X11 display server can interact with each other. 40 | This means that one application can intercept or inject events into another 41 | application. 42 | 43 | Without **OZ** or an alternate display server, there is no way to securely 44 | prevent applications from interacting with each other. An attacker could abuse 45 | this to perform malicious actions such as intercepting the keystrokes from 46 | another desktop application. To prevent these attacks, **OZ** sandboxes use 47 | **xpra** to render applications on the desktop. **Xpra** isolates applications 48 | by using a separate display server to render each application. Since the 49 | applications do not share the same display server, they cannot interact. 50 | 51 | For more technical details about **OZ** and its security features, see the 52 | following page: 53 | 54 | 55 | 56 | 57 | \newpage 58 | 59 | ### Enabling an OZ profile 60 | 61 | **OZ** profiles can be found in the following directory: 62 | ``` 63 | /var/lib/oz/cells.d 64 | ``` 65 | 66 | **OZ** automatically enables profiles in this directory. However, if you need to 67 | manually enable a profile, you can do so by running the **oz-setup** command to 68 | *install* the profile. 69 | 70 | The following example installs the profile for **evince**: 71 | ```{.bash} 72 | $ sudo oz-setup install evince 73 | ``` 74 | 75 | When the profile is installed, **OZ** will *divert* the path of the program 76 | executable. Instead of the program running directly, diverting it lets **OZ** 77 | start the program. So the next time it is started, the program will be sandboxed 78 | by **OZ**. 79 | 80 | ### Disabling an OZ profile 81 | 82 | If you want to run a previously sandboxed program outside of the sandbox, you 83 | must disable its profile. To disable a profile, run the **oz-setup** command 84 | with the *remove* option. 85 | 86 | The following example removes the profile for **evince**: 87 | ```{.bash} 88 | $ sudo oz-setup remove evince 89 | ``` 90 | 91 | When the profile is removed, **OZ** will undo the *divert* of the program path. 92 | The program will not run in the **OZ** sandbox the next time it is started. 93 | 94 | ### Viewing the status of an OZ profile 95 | 96 | The status of a program can also be viewed with the **oz-setup** command. 97 | 98 | The following example shows the status of **evince**: 99 | ```{.bash} 100 | $ sudo oz-setup status /usr/bin/evince 101 | ``` 102 | 103 | The command prints the following when **evince** profile is installed: 104 | ``` 105 | Package divert is installed for: /usr/bin/evince 106 | Package divert is installed for: /usr/bin/evince-thumbnailer 107 | Package divert is installed for: /usr/bin/evince-previewer 108 | ``` 109 | 110 | When the **evince** profile is not installed, the command prints the following: 111 | ``` 112 | Package divert is not installed for: /usr/bin/evince 113 | Package divert is not installed for: /usr/bin/evince-thumbnailer 114 | Package divert is not installed for: /usr/bin/evince-previewer 115 | ``` 116 | 117 | \newpage 118 | 119 | ### Creating an OZ profile 120 | 121 | In this section, we will walk through some of the options in a basic profile. 122 | 123 | **OZ** profiles are written in JSON. 124 | 125 | The following is the **OZ** profile for the **eog** image viewer: 126 | ```{.javascript} 127 | { 128 | "name": "eog" 129 | , "path": "/usr/bin/eog" 130 | , "allow_files": true 131 | , "xserver": { 132 | "enabled": true 133 | , "enable_tray": false 134 | , "tray_icon":"/usr/share/icons/hicolor/scalable/apps/eog.svg" 135 | } 136 | , "networking":{ 137 | "type":"empty" 138 | } 139 | , "whitelist": [ 140 | {"path":"/var/lib/oz/cells.d/eog-whitelist.seccomp", "read_only": true} 141 | ] 142 | , "blacklist": [ 143 | ] 144 | , "environment": [ 145 | {"name":"GTK_THEME", "value":"Adwaita:dark"} 146 | , {"name":"GTK2_RC_FILES", 147 | "value":"/usr/share/themes/Darklooks/gtk-2.0/gtkrc"} 148 | ] 149 | , "seccomp": { 150 | "mode":"whitelist" 151 | , "enforce": true 152 | , "whitelist":"/var/lib/oz/cells.d/eog-whitelist.seccomp" 153 | } 154 | } 155 | ``` 156 | 157 | > **Example OZ profile configuration options** 158 | > 159 | > *name*: The name of the profile 160 | > 161 | > *path*: The path to the program executable 162 | > 163 | > *allow_files*: Allow files to be passed as arguments to the program (such as 164 | > image files for **eog**) 165 | > 166 | > *xserver -> enabled*: Enable the use of the Xserver (**xpra**) 167 | > 168 | > *xserver -> enable_tray*: Enable the **xpra** diagnostic tray (defaults to 169 | > `false`, enabling it requires extra software) 170 | > 171 | > *xserver -> tray_icon*: The path to the tray icon 172 | > 173 | > *networking -> type*: The networking configuration type, *empty* disables 174 | > networking entirely 175 | > 176 | > *whitelist -> path*: The path of a file to add to the sandbox, in this case it 177 | > is the *seccomp whitelist* for **eog** 178 | > 179 | > *whitelist -> path -> read_only*: Whether or not the allowed file is 180 | > *read-only*, should be *true* in most cases 181 | > 182 | > *blacklist*: Removes access to a file in the sandbox, accepts the *path* 183 | > argument 184 | > 185 | > *environment -> name, value*: Adds environment variables by name and value to 186 | > the sandbox 187 | > 188 | > *seccomp -> mode*: Adds a seccomp policy (either *whitelist* or *blacklist*) 189 | > to the sandbox 190 | > 191 | > *seccomp -> enforce*": The seccomp enforcement mode 192 | > 193 | > *seccomp -> whitelist*: The path to the whitelist policy 194 | 195 | **OZ** supports a number of different profile configurations. More examples for 196 | real applications are located in the profiles directory: 197 | ``` 198 | /var/lib/oz/cells.d 199 | ``` 200 | 201 | Complete documentation for creating **OZ** profiles can be found here: 202 | 203 | 204 | 205 | \newpage 206 | 207 | ### Securing system calls with seccomp in OZ 208 | 209 | *Seccomp* is a feature of the Linux kernel to limit exposed system calls. As 210 | system calls provide a user interface to the kernel, they expose it to attacks. 211 | These attacks can let an attacker elevate their privileges on the computer. The 212 | **OZ** sandbox uses *seccomp* to protect against this type of attack. 213 | 214 | **OZ** supports *seccomp* policies on a per-application basis. *Seccomp* kills 215 | applications whenever they violate a policy. This protects the computer in cases 216 | where an attacker tries to exploit a vulnerability in the kernel that depends on 217 | the blocked system call. 218 | 219 | Some attacks also use system calls as part of their *payload*. A *payload* is 220 | the malicious code that runs as a result of a successful exploit. The *seccomp* 221 | policies in **OZ** can prevent *payloads* from running if they use a blocked 222 | system call. 223 | 224 | **OZ** supports **whitelist** or **blacklist** policies. Whitelist policies are 225 | *default deny*. This means that only system calls that are explicitly permitted 226 | will be allowed. All other system calls (those not on the **whitelist**) cause 227 | the application to be killed. 228 | 229 | **Blacklist** policies are *default allow*. This means that seccomp blocks system 230 | calls in the blacklist policy but allows all others (those not on the 231 | **blacklist**). 232 | 233 | **Whitelist** policies are appropriate when the application is well understood. 234 | By well understood, we mean that the behavior of the application is predictable 235 | enough to create a precise profile of allowed system calls. This is more secure 236 | than a **blacklist** because known behavior of the application is allowed but 237 | unknown behavior is blocked. The disadvantage of this approach is that the 238 | **whitelists** must be updated regularly to reflect the known behavior of the 239 | application. 240 | 241 | **Blacklist** policies are appropriate for applications that are not as well 242 | understood. We use them prior to the creation of a **whitelist** or if there is 243 | some other reason a **whitelist** cannot be created. 244 | 245 | **OZ** includes a generic **blacklist** that will work out-of-the-box with many 246 | applications. This policy blocks unusual or exotic system calls that 247 | applications do not normally use. 248 | 249 | The **OZ** generic **blacklist** is located here: 250 | ``` 251 | /var/lib/oz/cells.d/generic-blacklist.seccomp 252 | ``` 253 | 254 | In Subgraph OS, we try to create **whitelist** policies for all of our supported 255 | applications. 256 | 257 | See the Appendix for a complete list of system calls in Subgraph OS. You can use 258 | this reference to look up system call numbers when writing or debugging 259 | *seccomp* policies. 260 | 261 | \newpage 262 | 263 | ### Profiling applications with oz-seccomp-tracer 264 | 265 | **OZ** includes a tool to help with the creation and maintenance of seccomp 266 | **whitelists**. The **oz-seccomp-tracer** profiles applications as they run to 267 | determine the system calls that they use. This tool will generate a seccomp 268 | `whitelist` after it exits. 269 | 270 | To profile Firefox using **oz-seccomp-tracer**, run the following command: 271 | ```{.bash} 272 | $ oz-seccomp-tracer -train -output firefox-whitelist.seccomp /usr/bin/firefox \ 273 | 2>firefox_syscalls.txt 274 | ``` 275 | 276 | You can then use Firefox as you normally would. When you are finished, a seccomp 277 | **whitelist** will be saved to **firefox-whitelist.seccomp**. 278 | **oz-seccomp-tracer** prints all of the system calls from the application to 279 | **stdout**. So we also advise you to redirect this output to a separate file. 280 | We use **firefox_syscalls.txt** in this example. You could also redirect this 281 | output to **/dev/null** if you don't want to save it. 282 | 283 | ### Adding a seccomp policy to an OZ application profile 284 | 285 | Once you are satisfied with the **whitelist**, you can copy it to the following 286 | directory: 287 | ``` 288 | /var/lib/oz/cells.d 289 | ``` 290 | Using Firefox as an example, the following snippets from 291 | */var/lib/oz/cells.d/firefox.json* show how to apply the policy. 292 | 293 | First, the seccomp policy file must be added to the list of files allowed in 294 | the sandbox: 295 | ```{.javascript} 296 | "whitelist": [ 297 | , {"path":"/var/lib/oz/cells.d/firefox-whitelist.seccomp", 298 | "read_only": true} 299 | ] 300 | ``` 301 | 302 | Then the seccomp policy needs to be enabled to run in *enforce* mode: 303 | ```{.javascript} 304 | "seccomp": { 305 | "mode":"whitelist" 306 | , 307 | "whitelist":"/var/lib/oz/cells.d/firefox-whitelist.seccomp" 308 | , "enforce": true 309 | } 310 | ``` 311 | 312 | Lastly, the **OZ** any sandbox running for this profile should be killed by 313 | closing the application or using: 314 | ```{.bash} 315 | $ oz list 316 | $ oz kill 317 | ``` 318 | The daemon can now be reloaded to read the profile changes: 319 | ```{.bash} 320 | $ sudo systemctl reload oz-daemon.service 321 | ``` 322 | 323 | \newpage 324 | 325 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_03_tor.md: -------------------------------------------------------------------------------- 1 | ## Anonymizing communications with Tor 2 | 3 | *Tor* is an essential privacy tool that provides anonymity to its users. In 4 | particular, Tor hides the location of its users. By location, we mean your IP 5 | address (which can also be used to geo-locate your computer). 6 | 7 | Tor hides your location by relaying your traffic through a random series of 8 | network connections (called a *circuit*). While your traffic passes through the 9 | *hops* in this circuit, the source and destination of the traffic are hidden. The 10 | traffic eventually leaves the *circuit* through an *exit node*. The *exit node* 11 | relays the traffic to its final destination but is also unaware of the source. 12 | They are called *exit nodes* because they are the point where the traffic leaves 13 | the Tor network to reach its destination on the regular Internet. *Exit nodes* 14 | may observe or tamper with the traffic en-route to its destination, unless an 15 | additional layer of encryption is applied such as *TLS*. 16 | 17 | Due to the possibility that some *exit nodes* are malicious, we strongly advise 18 | you to use Tor with an additional layer of encryption. This means 19 | connecting to websites over *HTTPS* only, using TLS with applications such as 20 | **Icedove** or **Hexchat**, etc. 21 | 22 | **NOTE**: Tor hidden services provide a way to send network traffic *only* 23 | through the Tor network. This eliminates the risks involved when the traffic 24 | passes through an *exit node* to the regular Internet. However, this requires 25 | that the destination service is configured to run as a hidden service. It also 26 | adds more latency to the network traffic because it must pass through more 27 | *hops* to reach the hidden service. Tor hidden services are discussed in further 28 | detail in other sections of this book. 29 | 30 | More information about Tor can be found here: 31 | 32 | 33 | 34 | \newpage 35 | 36 | ### Tor integration in Subgraph OS 37 | 38 | Subgraph OS is integrated with the Tor anonymity network. We include many 39 | applications that are designed to be used with Tor. These include: 40 | 41 | * **Tor Browser** for browsing the web anonymously and accessing Tor hidden 42 | service websites 43 | * **OnionShare** for sharing files anonymously over Tor 44 | * **Ricochet** for chatting anonymously of Tor 45 | * **CoyIM** instant messager, which supports connecting to the *.onion* 46 | addresses for *XMPP/Jabber* chat servers 47 | 48 | Other parts of Subgraph OS are engineered to integrate with Tor seamlessly. The 49 | **Metaproxy** routes non-Tor applications over Tor. Our **Oz** sandbox also lets 50 | applications work seamlessly with Tor. We also include a Gnome Shell extension 51 | that monitors that status of connections to the Tor network. Lastly, 52 | **ROFLCopTor** is a filter for the Tor control port that enforces security 53 | policies on applications that run Tor control commands. 54 | 55 | \newpage 56 | 57 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_04_metaproxy.md: -------------------------------------------------------------------------------- 1 | ## Routing applications through Tor with Subgraph Metaproxy 2 | 3 | The **Metaproxy** is an important part of Subgraph OS. It runs in the background 4 | to help applications connect through the Tor network. This is done 5 | transparently, even with applications that are not configured or designed to 6 | work with Tor. 7 | 8 | On other operating systems, users must specifically configure applications to 9 | connect to the Internet through Tor. This normally requires the user to 10 | configure proxy settings of the application to connect through Tor's built-in 11 | proxies. Some applications do not support or honor proxy settings. To use Tor 12 | with these applications, users often run them with using a command-line helper 13 | called **torsocks** to *torify* the application. This is a lot of work for users. 14 | 15 | Configuring proxies or *torifying* applications by hand is not an adequate 16 | solution for Subgraph OS. Usability and maintainability are issues with this 17 | approach. In Subgraph OS, some applications simply would not work if there is no 18 | easy way to route them through Tor. This is because Subgraph OS blocks outgoing 19 | connections that are not routed through Tor. This is to prevent accidental 20 | privacy leaks. If an application has no way to communicate over Tor, it may not 21 | be able to access the network at all. 22 | 23 | The **Metaproxy** addresses this problem by automatically relaying outgoing 24 | connections through Tor. When we say this is done transparently, we mean the 25 | following two things: 26 | 27 | 1. Users do not have to manually *torify* their applications or otherwise 28 | configure them to use Tor 29 | 2. Applications that are already configured to use Tor are ignored by the 30 | **Metaproxy**, therefore, it only helps those applications which need it 31 | 32 | \newpage 33 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_05_roflcoptor.md: -------------------------------------------------------------------------------- 1 | ## Securing the Tor control port with ROFLCopTor 2 | 3 | The Tor service is managed by a control protocol. This lets users perform 4 | various actions such as querying information about Tor connections, starting 5 | hidden services, and changing configuration options. However, most applications do not 6 | need all of these features. These extra features may actually introduce security 7 | and privacy risks if someone gains unauthorized access to the control port. To 8 | mitigate these risks, Subgraph OS includes a control port filter called 9 | *ROFLCopTor*. 10 | 11 | *ROFLCopTor* is a proxy server that is placed between Tor control clients and the 12 | Tor control server port. *ROFLCopTor* handles authentication itself, meaning 13 | clients do not need to know the authentication credentials or run with higher 14 | privileges to access to Tor control port. It intercepts the incoming commands 15 | and outgoing responses. *ROFLCopTor* enforces policies on a per-application 16 | basis for the traffic between the Tor control clients and the server. 17 | 18 | *ROFLCopTor* supports policies that are bi-directional. This means that a policy 19 | can filter both the incoming commands and the outgoing responses from the Tor 20 | control port. Policies can also replace command and response strings. 21 | Replacements can be used to filter sensitive information from Tor control port 22 | responses. 23 | 24 | *ROFLCopTor* has a number of default policies for applications in Subgraph OS that 25 | require access to the Tor control port. The policies work without modification 26 | for most use-cases. This section describes how to profile applications to create 27 | new policies or modify existing ones. 28 | 29 | ### Profiling applications with ROFLCopTor 30 | 31 | *ROFLCopTor* can profile applications to determine the Tor control commands that 32 | they run on a regular basis. This makes it easier to create or edit policies. 33 | 34 | Before profiling applications, you should stop the currently running version of 35 | *ROFLCopTor*: 36 | ```{.bash} 37 | $ sudo systemctl stop roflcoptor 38 | ``` 39 | 40 | To begin profiling, you must start *ROFLCopTor* in *watch* mode: 41 | ```{.bash} 42 | $ sudo -u roflcoptor roflcoptor watch -log_level DEBUG \ 43 | -config /etc/roflcoptor/roflcoptor_config.json 44 | 45 | ``` 46 | 47 | The log shows some of the commands that applications tried to run: 48 | ``` 49 | 18:21:53 - DEBU 017 connection received tcp:127.0.0.1:44860 -> 50 | tcp:127.0.0.1:9051 51 | 18:21:55 - ERRO 018 filter policy for gnome-shell-torstatus DENY: A->T: [GETCONF 52 | ORPort] 53 | 18:21:55 - ERRO 019 filter policy for gnome-shell-torstatus DENY: A->T: [GETINFO 54 | events/names] 55 | 18:21:55 - ERRO 01a filter policy for gnome-shell-torstatus DENY: A->T: 56 | [SETEVENTS NOTICE NS NEWDESC NEWCONSENSUS] 57 | 18:21:55 - ERRO 01b filter policy for gnome-shell-torstatus DENY: A->T: [GETINFO 58 | process/user] 59 | 18:21:55 - ERRO 01c filter policy for gnome-shell-torstatus DENY: A->T: [GETINFO 60 | process/pid] 61 | ... 62 | ``` 63 | 64 | Press **Ctrl-C** to stop the *ROFLCopTor* watch process. Make sure to restart 65 | *ROFLCopTor* normally after you are done profiling. Run the following command to 66 | restart *ROFLCopTor*: 67 | ```{.bash} 68 | $ sudo systemctl restart roflcoptor 69 | ``` 70 | 71 | ### Editing ROFLCopTor policies 72 | 73 | Once you have a list of commands required by an application, you can create or 74 | edit a policy. 75 | 76 | *ROFLCopTor* policies are written in JSON. Policies can be found in the following 77 | directory on Subgraph OS: 78 | ``` 79 | /etc/roflcoptor/filters/ 80 | ``` 81 | 82 | The following is a simple policy for the Tor Status Gnome shell extension in 83 | Subgraph OS: 84 | ```{.javascript} 85 | { 86 | "Name": "gnome-shell-torstatus", 87 | "AuthNetAddr" : "tcp", 88 | "AuthAddr" : "127.0.0.1:9051", 89 | "client-allowed" : ["GETINFO status/bootstrap-phase", "SIGNAL NEWNYM"], 90 | "client-allowed-prefixes" : [], 91 | "client-replacements" : {}, 92 | "client-replacement-prefixes" : {}, 93 | "server-allowed" : ["250 OK"], 94 | "server-allowed-prefixes" : ["250-status/bootstrap-phase="], 95 | "server-replacement-prefixes" : {} 96 | } 97 | ``` 98 | 99 | > **ROFLCopTor policy configuration options** 100 | > 101 | > *Name*: The name of the application to apply the policy to 102 | > 103 | > *AuthNetAddr*: The protocol used by the Tor control port 104 | > 105 | > *AuthAddr*: The address of the Tor control port 106 | > 107 | > *client-allowed*: The list of commands allowed by the client 108 | > 109 | > *client-allowed-prefixes*: A list of prefixes for partial allowed client 110 | >commands (commands where the suffix varies) 111 | > 112 | > *client-replacements*: A list of commands to replace and their replacement 113 | > strings 114 | > 115 | > *client-replacement-prefixes*: A list of client command prefixes to replace 116 | > and their replacement strings (for commands where the suffix varies) 117 | > 118 | > *server-allowed*: The list of responses allowed by the server 119 | > 120 | > *server-allowed-prefixes*: A list of prefixes for partial allowed server 121 | > responses (responds where the suffix varies) 122 | > 123 | > *server-replacement-prefixes*: A list of server response prefixes to replace 124 | > and their replacement strings (for responses where the suffix varies) 125 | 126 | The most common configuration task is to add new commands and responses to the 127 | *client-allowed*, *client-allowed-prefixes*, *server-allowed*, and 128 | *server-allowed-prefixes* options. 129 | 130 | More documentation on configuring and using ROFLCopTor is located on the 131 | following page: 132 | 133 | 134 | \newpage 135 | 136 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_06_grsecurity.md: -------------------------------------------------------------------------------- 1 | ## Hardening the operating system and applications with Grsecurity 2 | 3 | **Grsecurity** is a third-party security enhancement to the Linux kernel. It is 4 | developed and maintained by the **Grsecurity** team. It is implemented as a patch 5 | to the upstream Linux kernel. Subgraph OS ships with a kernel that is patched 6 | with **Grsecurity**. 7 | 8 | For more information about **Grsecurity**, see the following page: 9 | 10 | 11 | 12 | ### Configuring PaX flags with Paxrat 13 | 14 | **Paxrat** is a utility in Subgraph OS for maintaining the *PaX flags* of 15 | applications on the computer. 16 | 17 | 18 | > *What is PaX?* 19 | > 20 | > *PaX* is a feature of *Grsecurity* that provides *memory protection*. Many security 21 | > vulnerabilities in applications and the Linux kernel allow attackers to 22 | > corrupt process memory. *Memory corruption* can be exploited to run the 23 | > attackers *payload* of malicious code. 24 | > 25 | > PaX protects the computer from *memory corruption* using a number of novel 26 | > techniques such as: 27 | > 28 | > 1. Randomizing the layout of process memory or *ASLR* (Address Space Layout 29 | > Randomization), making it harder for attackers to guess where their 30 | > malicious *payload* is stored in process memory 31 | > 2. Making memory pages *non-executable*, meaning that an attacker's *payload* 32 | > cannot run if stored in *non-executable* memory 33 | > 34 | > *PaX* includes other *memory protection* and *control flow integrity* features 35 | > so that it is more difficult for attackers to exploit *memory corruption* 36 | > vulnerabilities in applications and the kernel. 37 | > 38 | > *PaX* does not prevent all vulnerabilities but it complicates attacks. The 39 | > difference to an attacker is that with *PaX* they may be required to exploit 40 | > multiple vulnerabilities to achieve the same effect as a single vulnerability. 41 | > 42 | > More information about *PaX* can be found here: 43 | > 44 | > 45 | 46 | *PaX* works by killing applications that violate its security policies. This 47 | *proactively* prevents attacks from succeeding. However, as part of their normal 48 | functions, some applications perform non-malicious actions that violate the 49 | security policies. *PaX flags* are exceptions to these policies. They let 50 | applications run normally without being killed by *PaX* when they perform an 51 | action that appears to violate policies. 52 | 53 | Applications such as web browsers need *PaX flags* to be set because they 54 | perform actions such as *JIT* (Just in Time compilation). To *PaX*, *JIT* has 55 | the same profile as an attack. Applications that use a *JIT* compiler 56 | must be flagged as exceptions so that they are not killed. 57 | 58 | **Paxrat** keeps track of the *PaX flags* for applications in Subgraph OS. It is 59 | designed to maintain the *PaX* flags between application updates. **Paxrat** 60 | runs when the system updates software, automatically re-applying flags to 61 | upgraded applications. 62 | 63 | **Paxrat** can only maintain the flags it knows about. If a user discovers that 64 | *PaX* is killing an application, the configuration must be changed to disable 65 | some *PaX flags*. Instructions are provided in this guide for changing the 66 | **Paxrat** configuration. We also advise users to report the exception to us so 67 | that we can update the configuration for everybody. 68 | 69 | **Paxrat** configuration files are written in JSON. They are stored in the 70 | following directory: 71 | ``` 72 | /etc/paxrat 73 | ``` 74 | 75 | The following is a snippet of a *PaX flag* configuration for **Tor Browser**: 76 | ```{.javascript} 77 | "/home/user/.local/share/torbrowser/tbb/x86_64/tor-browser_en-US/Browser/firefox": 78 | { 79 | "flags": "m", 80 | "nonroot": true 81 | } 82 | ``` 83 | 84 | > **Paxrat configuration options** 85 | > 86 | > The first line of the configuration (in quotes) is the path to the 87 | > application. 88 | > In the above example, it is: 89 | > "/home/user/.local/share/torbrowser/tbb/x86_64/tor-browser_en-US/Browser/firefox" 90 | > 91 | > *flags*: This a string of letters representing the various PaX flags 92 | > 93 | > *nonroot*: This indicates whether the application is owned by the *root* user 94 | > or not, it is *false* by default but *true* in the example because the 95 | > **Tor Browser** application is owned by a normal user 96 | > 97 | > **NOTE**: As a security precaution, **Paxrat** will not apply *PaX flags* to 98 | > an application that is owned by a *nonroot* user unless the *nonroot* option 99 | > is set to *true*. 100 | 101 | There are a number of different *PaX flags* that can be *enabled* or *disabled*. 102 | Most are *enabled* by default and must be *disabled*. *Disabled* flags are 103 | represented by a lower-case letter such as **m**. Upper-case letters such as 104 | **M** represent *enabled* flags. 105 | 106 | > **PaX flags** 107 | > 108 | > *P/p*: *Enable/disable* PAGEXEC 109 | > 110 | > *E/e*: *Enable/disable* EMUTRAMP 111 | > 112 | > *M/m*: *Enable/disable* MPROTECT 113 | > 114 | > *R/r*: *Enable/disable* RANDMAP 115 | > 116 | > *X/x*: *Enable/disable* RANDEXEC 117 | > 118 | > *S/x*: *Enable/disable* SEGMEXEC 119 | > 120 | > 121 | > A detailed description of these flags can be found on the following page: 122 | > 123 | > 124 | 125 | Working examples can be found in the Subgraph OS **Paxrat** configuration files: 126 | ``` 127 | /etc/paxrat/paxrat.conf 128 | ``` 129 | 130 | ### Applying PaX flags 131 | 132 | *PaX flags* must be re-applied after any configuration changes. Run the 133 | following command to re-apply *PaX flags*: 134 | ``` 135 | $ sudo paxrat 136 | ``` 137 | 138 | \newpage 139 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_07_macouflage.md: -------------------------------------------------------------------------------- 1 | ## Anonymizing MAC addresses with Macouflage 2 | 3 | MAC addresses are the unique identifiers for the network interface on the computer 4 | (such as Ethernet ports and WIFI cards). Due to their unique nature, they can 5 | also compromise the privacy of the user. 6 | 7 | When connecting to a network, it is possible for other devices on the network to 8 | see the MAC address of the network interface that is connected. While this is 9 | not much of a concern on networks you trust such as your home network, it may 10 | compromise your privacy on those who do not trust. On untrustworthy or hostile 11 | networks, uniquely identifying characteristics such as the MAC address may 12 | allow others to track your computer. 13 | 14 | Subgraph OS mitigates this privacy risk by always creating random MAC 15 | addresses for all of your network interfaces. Each time one of your interfaces 16 | connects to a network, it will use a different MAC address. This helps to 17 | anonymize you across different networks or when connecting to the same network 18 | over and over again. 19 | 20 | \newpage 21 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_08_usblockout.md: -------------------------------------------------------------------------------- 1 | ## Preventing unauthorized USB access with USB Lockout 2 | 3 | **USB Lockout** is a background feature in Subgraph OS. It protects your 4 | computer from unauthorized USB access while your desktop session is locked or 5 | you have logged out. 6 | 7 | **USB Lockout** is intended for situations where your computer must be left 8 | unattended for short periods. Particularly, in situations where you do not fear 9 | your computer will be stolen but you do do not want to expose it to other risks 10 | while unattended. 11 | 12 | Normally, when you lock the screen or logout, people may still insert a 13 | malicious USB device into the computer. While the computer is running, a 14 | malicious device can easily compromise it. **USB Lockout** denies all access for 15 | new USB devices while the screen is locked or the user is logged out. 16 | 17 | **USB Lockout** works by monitoring the state of the desktop session. When the 18 | session is locked or logged out, **USB Lockout** enables the Grsecurity *Deny 19 | New USB* setting. When the user unlocks the screen or logs back in, this setting 20 | is disabled, allowing access to new USB devices once again. 21 | 22 | See the following page page for more information about the Grsecurity *Deny New 23 | USB* feature: 24 | 25 | 26 | 27 | 28 | ### Enabling/disabling USB Lockout 29 | 30 | While **USB Lockout** runs automatically in the background, you can manually 31 | *enable* or *disable* it. 32 | 33 | Run the following command to *enable* **USB Lockout**: 34 | ```{.bash} 35 | $ usblockout --enable 36 | ``` 37 | 38 | Run the following command to *disable* **USB Lockout**: 39 | ```{.bash} 40 | $ usblockout --disable 41 | ``` 42 | 43 | \newpage 44 | 45 | -------------------------------------------------------------------------------- /05_features_and_advanced_usage_09_virtualmachines.md: -------------------------------------------------------------------------------- 1 | ## Using virtual machines in Subgraph OS 2 | 3 | Contrary to popular belief, there is nothing that stops the use of virtual 4 | machines in Subgraph OS. While the *Grsecurity* kernel is not compatible with 5 | VirtualBox, **Qemu/KVM** works as expected. However, you must install 6 | **Qemu/KVM** yourself if you want to run virtual machines. 7 | 8 | Running the following command will install **Qemu/KVM**: 9 | ```{.bash} 10 | $ sudo apt install qemu-system qemu-kvm qemu-utils 11 | ``` 12 | 13 | The following sections are recipes on how to use **Qemu/KVM** in Subgraph OS. 14 | They are similar to our own workflows for developing and testing Subgraph OS. 15 | **Qemu/KVM** supports many more options than what we use in these tutorials. 16 | For more detailed information regarding the operation of **Qemu/KVM** 17 | virtual machines, see the official **Qemu** manual: 18 | 19 | 20 | 21 | There are multiple third-party graphical user interfaces for **Qemu/KVM**. These 22 | may make it easier to configure and manage virtual machines. You can explore the 23 | various options by visiting these pages: 24 | 25 | * 26 | * 27 | * 28 | * 29 | 30 | \newpage 31 | 32 | ### Simple usage with Virt-Manager 33 | 34 | One option is to use the **virt-manager** frontend for **libvirt** and **Qemu/KVM**. 35 | This requires some extra dependencies, but is far more user friendly. 36 | 37 | You will want to install it along with the following dependencies: 38 | ```{.bash} 39 | $ sudo apt install virt-manager libvirt-daemon virt-viewer gir1.2-spice-client-gtk-3.0 40 | ``` 41 | 42 | After the installation is complete you can launch **virt-manager** from __GNOME Activities__. 43 | 44 | #### Configuring virt-manager for session mode 45 | 46 | On first launch we are prompted with an error about a failed connection to the libvirt daemon: 47 | 48 | ![Virt Manager First Launch Error](static/images/virt-manager_00_firtlaunch_error.png) 49 | 50 | \clearpage 51 | 52 | This error can be ignored; to avoid it the future we will right-click on the only entry in the list 53 | `QEMU/KVM - Not Running` and delete it. 54 | 55 | ![Virt Manager Delete Default Connection](static/images/virt-manager_00_firtlaunch_delete.png) 56 | 57 | \clearpage 58 | 59 | Now we need to add a session mode connection. This will allow us to use unpriviledged virtual machines. 60 | For this go into the the `File` menu, and select `Add Connection...`. 61 | A new window will appear, you will need to select `QEMU/KVM user session` in the hypervisor popup menu. 62 | 63 | ![Virt Manager Select User Session Hypervisor](static/images/virt-manager_00_hypervisor_select.png) 64 | 65 | \clearpage 66 | 67 | We are now ready to use **virt-manager**! 68 | 69 | ![Virt Manager Ready](static/images/virt-manager_00_virtman_ready.png) 70 | 71 | \newpage 72 | 73 | #### Creating a simple virtual machine in virt-manager 74 | 75 | Click on the create new virtual machine button and you will be prompted to start configuring the virtual machine: 76 | 77 | ![Virt Manager Create New Virtual Machine](static/images/virt-manager_01_createnew.png) 78 | 79 | When selecting a disk image to install, you will probably notice that libvirt looks in an odd location for disk images. 80 | The default location is `~/.local/share/libvirt/images`. You can add more, or more simply you can just ignore this, 81 | and select **Browse Local** to freely select and image. 82 | 83 | ![Virt Manager Image Browser](static/images/virt-manager_01_browser.png) 84 | 85 | \newpage 86 | 87 | Continue with the configuration of the basic attributes of your virtual machine: 88 | 89 | ![Virt Manager CPU And RAM Configuration](static/images/virt-manager_01_cpuram.png) 90 | 91 | ![Virt Manager Disk Image Configuration](static/images/virt-manager_01_diskimage.png) 92 | 93 | ![Virt Manager Final Configuration](static/images/virt-manager_01_name.png) 94 | 95 | \newpage 96 | 97 | Once done your virtual machine will start automatically: 98 | 99 | ![Virt Manager Running Virtual Machine](static/images/virt-manager_01_done.png) 100 | 101 | You can proceed with a regular installation, use a live image, etc. 102 | 103 | > ***Qemu/KVM guest integration** 104 | > 105 | > You may install the **qemu-guest-agent** and/or **spice-vdagent** and/or **xserver-xorg-video-qxl** in the running 106 | virtual machine to improve integration. 107 | > 108 | > This is not strictly necessary and may present extra security considerations. 109 | 110 | \newpage 111 | 112 | ### Command line usage 113 | 114 | For a more minimal, and sometimes more advanced, usage one may also use **Qemu/KVM** 115 | directly with the command line interface. 116 | 117 | #### Creating a basic Linux virtual machine with Qemu 118 | 119 | Prior to creating the virtual machine, you should create a virtual hard-drive 120 | image for it: 121 | 122 | ```{.bash} 123 | $ qemu-img create -f qcow2 disk.qcow2 8G 124 | ``` 125 | 126 | Your virtual hard-drive is now ready for use. Run the following command to 127 | test a virtual machine with the hard-drive: 128 | 129 | ```{.bash} 130 | $ qemu-system-x86_64 -enable-kvm -hda ./disk.qcow2 -m 4096 131 | ``` 132 | 133 | To start a virtual machine with an operating system ISO attached to the virtual 134 | CDROM, run the following command: 135 | 136 | ```{.bash} 137 | $ qemu-system-x86_64 -enable-kvm -hda ./disk.qcow2 -m 4096 \ 138 | -cdrom ./subgraph-os-alpha_2016-06-16_2.iso -boot d 139 | ``` 140 | 141 | > **Qemu/KVM options** 142 | > 143 | > *-enable-kvm*: enables **KVM** virtualisation, which is faster than 144 | > **Qemu's** emulation 145 | > 146 | > *-hda*: This attaches the virtual hard-drive you created 147 | > 148 | > *-m*: This allocates RAM to the virtual machine (4096MB in the example) 149 | > 150 | > *-cdrom*: The path to the operation system ISO 151 | > 152 | > *-boot*: This specifies the boot order for the virtual machine, *d* is the 153 | > virtual CDROM 154 | 155 | This example can be adapted to run the Linux distribution of your choice inside of 156 | a virtual machine. 157 | 158 | \newpage 159 | 160 | #### Creating an advanced Debian Stretch virtual machine using debootstrap 161 | 162 | To have more control over the installation of Debian inside of a virtual 163 | machine, you can use **debootstrap** to install the operating system. Another 164 | advantage of this approach is that you can avoid all of the installation dialogs 165 | of the **Debian installer**. 166 | 167 | This section will show how to install Debian Stretch with the *Grsecurity* 168 | kernel from Subgraph OS. 169 | 170 | ##### Create a virtual hard-drive image for the operating system 171 | 172 | To begin the install, you must set up a virtual hard-drive image. Follow these 173 | steps to set it up: 174 | 175 | 1. Run the following command to create a sparse virtual hard-drive image: 176 | ```{.bash} 177 | $ truncate --size 8G ./disk.img 178 | ``` 179 | 180 | 2. To format the virtual hard-drive run the following command: 181 | ```{.bash} 182 | $ /sbin/mkfs.ext4 ./disk.img 183 | ``` 184 | After formatting the hard-drive, you can create a proper partition table. We 185 | will skip this step in the tutorial as it is not strictly necessary to run the 186 | virtual machine. 187 | 188 | 3. Mount the virtual hard-drive: 189 | ```{.bash} 190 | $ sudo mount -o loop ./disk.img /mnt 191 | ``` 192 | 193 | **NOTE:** You should ensure there is enough free space in the image you 194 | create. You may want to allocate twice as much if you want to convert the image 195 | later on. 196 | 197 | 198 | The sparse virtual hard-drive image you created will only use as much space as 199 | it requires. 200 | 201 | Run the following command to show how much space is used by the image: 202 | 203 | ```{.bash} 204 | $ du -sh disk.img 205 | ``` 206 | 207 | The amount shown is a fraction of the total amount specified in the *truncate* 208 | command: 209 | ``` 210 | 189M disk.img 211 | ``` 212 | 213 | To verify the total amount that was specified in the *truncate* command, run 214 | this command: 215 | ```{.bash} 216 | $ du --apparent-size -sh disk.img 217 | ``` 218 | 219 | The total amount should correspond with what was specified when you ran 220 | *truncate*: 221 | ``` 222 | 8.0G disk.img 223 | 224 | ``` 225 | 226 | ##### Installing the operating system with deboostrap 227 | 228 | Now that the virtual disk-image is created, we can now use **debootstrap** to 229 | install Debian Stretch. Follow these steps to install it: 230 | 231 | 1. Run **debootstrap** to install the operating system: 232 | ```{.bash} 233 | $ sudo debootstrap --variant=mintbase --include=systemd-sysv stretch /mnt 234 | ``` 235 | 236 | 2. Set a *root* password for the installed operating system: 237 | ```{.bash} 238 | $ sudo chroot /mnt passwd 239 | ``` 240 | 241 | 3. Create a standard fstab configuration: 242 | ```{.bash} 243 | $ sudo tee /mnt/etc/fstab << EOL 244 | /dev/sda / ext4 defaults,errors=remount-ro 0 1 245 | EOL 246 | ``` 247 | 248 | ##### Installing the Grsecurity kernel in the operating system 249 | 250 | Run the following commands to install the Subgraph OS *Grsecurity* kernel in 251 | your virtual machine: 252 | ```{.bash} 253 | $ cd /tmp 254 | $ apt-get download linux-{image,headers}-grsec-amd64-subgraph linux-{image,headers}-$(uname -r) 255 | $ sudo cp ./linux-{image,headers}-$(uname -r) /mnt/tmp 256 | $ sudo chroot /mnt 257 | $ dpkg -i /tmp/linux-{image,headers}-* 258 | $ update-initramfs -u -k all 259 | $ exit 260 | ``` 261 | 262 | 263 | The kernel and initramfs are inside of your mounted virtual hard-drive image. 264 | You must copy them to a directory on your computer to boot the virtual machine 265 | using these files. Run the following command to copy the files to the directory 266 | you want to start the virtual machine from: 267 | ```{.bash} 268 | $ cp /mnt/boot/vmlinuz--amd64 /mnt/boot/initrd.img--amd64 \ 269 | /home/user/path/to/vm 270 | ``` 271 | 272 | ##### Finalizing the installation of the operating system 273 | 274 | As the final step, we will sync the filesystem and unmount the virtual 275 | hard-drive image: 276 | ```{.bash} 277 | $ sync 278 | $ sudo umount /mnt 279 | ``` 280 | 281 | (Optional) If you prefer, you may convert the virtual hard-drive image to the 282 | *qcow2* format: 283 | 284 | ```{.bash} 285 | $ qemu-img convert -f raw -O qcow2 ./disk.img ./disk.qcow2 286 | ``` 287 | 288 | ##### Starting the Debian Stretch virtual machine 289 | 290 | Now you are ready to start the virtual machine. Run the following command to 291 | start it: 292 | 293 | ```{.bash} 294 | $ qemu-system-x86_64 -enable-kvm -hda ./disk.qcow2 \ 295 | -kernel ./vmlinuz--amd64 \ 296 | -initrd ./initrd.img--amd64 \ 297 | -append root=/dev/sda 298 | ``` 299 | **NOTE:** This assumes you converted the virtual hard-drive image to the 300 | *qcow2*. If not, replace **disk.qcow2** with the correct name of your image. 301 | 302 | > **Qemu/KVM options** 303 | > 304 | > This section uses some new options for **Qemu/KVM**. 305 | > 306 | > *-kernel*: This is the operating system kernel to boot when starting a virtual 307 | > machine 308 | > 309 | > *-initrd*: This is the initramfs to boot when starting a virtual machine 310 | > 311 | > *-append*: These are options to append to the kernel command line when 312 | > starting a virtual machine 313 | 314 | 315 | If you want to install grub to keep the kernel and initrd images inside the 316 | virtual machine you'll have to create a full partition table. You may also need 317 | to create a separate **/boot** partition. But this is out of scope for this 318 | tutorial. 319 | 320 | #### Setting up simple networking in Qemu/KVM 321 | 322 | By default, **Qemu** will transparently *NAT* your virtual machines to the host 323 | network. This can be disabled by using the **-net none** flag. 324 | 325 | Alternatively, you can also open simple tunnels between the host and the 326 | virtual machine using the port redirection mechanism with the **-redir** flag: 327 | 328 | ``` 329 | -redir tcp:55700::55700 330 | ``` 331 | 332 | For more on networking in **Qemu/KVM** see: 333 | 334 | * 335 | * 336 | 337 | \newpage 338 | 339 | ### Additional documentation 340 | 341 | * 342 | 343 | \newpage 344 | 345 | -------------------------------------------------------------------------------- /06_appendix_01_intro.md: -------------------------------------------------------------------------------- 1 | \appendix 2 | 3 | # Appendix 4 | 5 | \newpage 6 | 7 | -------------------------------------------------------------------------------- /06_appendix_02_syscalls_01.md: -------------------------------------------------------------------------------- 1 | ## System call table 2 | 3 | This section includes the Linux system call table for 64-bit Intel computers. 4 | You can use the table to look up the corresponding numbers for system calls. 5 | This will help when writing or debugging *seccomp* policies for the **Oz** 6 | sandbox. The numbers are presented in decimal and hexadecimal format. 7 | 8 | 9 | -------------------------------------------------------------------------------- /06_appendix_02_syscalls_02.md: -------------------------------------------------------------------------------- 1 | Syscall(dec) Syscall(hex) System Call 2 | ------------ ------------ ------------ 3 | 0 0x0 read 4 | 1 0x1 write 5 | 2 0x2 open 6 | 3 0x3 close 7 | 4 0x4 stat 8 | 5 0x5 fstat 9 | 6 0x6 lstat 10 | 7 0x7 poll 11 | 8 0x8 lseek 12 | 9 0x9 mmap 13 | 10 0xa mprotect 14 | 11 0xb munmap 15 | 12 0xc brk 16 | 13 0xd rt_sigaction 17 | 14 0xe rt_sigprocmask 18 | 15 0xf rt_sigreturn 19 | 16 0x10 ioctl 20 | 17 0x11 pread64 21 | 18 0x12 pwrite64 22 | 19 0x13 readv 23 | 20 0x14 writev 24 | 21 0x15 access 25 | 22 0x16 pipe 26 | 23 0x17 select 27 | 24 0x18 sched_yield 28 | 25 0x19 mremap 29 | 26 0x1a msync 30 | 27 0x1b mincore 31 | 28 0x1c madvise 32 | 29 0x1d shmget 33 | 30 0x1e shmat 34 | 31 0x1f shmctl 35 | 32 0x20 dup 36 | 33 0x21 dup2 37 | 34 0x22 pause 38 | 35 0x23 nanosleep 39 | 36 0x24 getitimer 40 | 37 0x25 alarm 41 | 38 0x26 setitimer 42 | 39 0x27 getpid 43 | 40 0x28 sendfile 44 | 41 0x29 socket 45 | 42 0x2a connect 46 | 43 0x2b accept 47 | 44 0x2c sendto 48 | 45 0x2d recvfrom 49 | 46 0x2e sendmsg 50 | 47 0x2f recvmsg 51 | 48 0x30 shutdown 52 | 49 0x31 bind 53 | 50 0x32 listen 54 | 51 0x33 getsockname 55 | 52 0x34 getpeername 56 | 53 0x35 socketpair 57 | 54 0x36 setsockopt 58 | 55 0x37 getsockopt 59 | 56 0x38 clone 60 | 57 0x39 fork 61 | 58 0x3a vfork 62 | 59 0x3b execve 63 | 60 0x3c exit 64 | 61 0x3d wait4 65 | 62 0x3e kill 66 | 63 0x3f uname 67 | 64 0x40 semget 68 | 65 0x41 semop 69 | 66 0x42 semctl 70 | 67 0x43 shmdt 71 | 68 0x44 msgget 72 | 69 0x45 msgsnd 73 | 70 0x46 msgrcv 74 | 71 0x47 msgctl 75 | 72 0x48 fcntl 76 | 73 0x49 flock 77 | 74 0x4a fsync 78 | 75 0x4b fdatasync 79 | 76 0x4c truncate 80 | 77 0x4d ftruncate 81 | 78 0x4e getdents 82 | 79 0x4f getcwd 83 | 80 0x50 chdir 84 | 81 0x51 fchdir 85 | 82 0x52 rename 86 | 83 0x53 mkdir 87 | 84 0x54 rmdir 88 | 85 0x55 creat 89 | 86 0x56 link 90 | 87 0x57 unlink 91 | 88 0x58 symlink 92 | 89 0x59 readlink 93 | 90 0x5a chmod 94 | 91 0x5b fchmod 95 | 92 0x5c chown 96 | 93 0x5d fchown 97 | 94 0x5e lchown 98 | 95 0x5f umask 99 | 96 0x60 gettimeofday 100 | 97 0x61 getrlimit 101 | 98 0x62 getrusage 102 | 99 0x63 sysinfo 103 | 100 0x64 times 104 | 101 0x65 ptrace 105 | 102 0x66 getuid 106 | 103 0x67 syslog 107 | 104 0x68 getgid 108 | 105 0x69 setuid 109 | 106 0x6a setgid 110 | 107 0x6b geteuid 111 | 108 0x6c getegid 112 | 109 0x6d setpgid 113 | 110 0x6e getppid 114 | 111 0x6f getpgrp 115 | 112 0x70 setsid 116 | 113 0x71 setreuid 117 | 114 0x72 setregid 118 | 115 0x73 getgroups 119 | 116 0x74 setgroups 120 | 117 0x75 setresuid 121 | 118 0x76 getresuid 122 | 119 0x77 setresgid 123 | 120 0x78 getresgid 124 | 121 0x79 getpgid 125 | 122 0x7a setfsuid 126 | 123 0x7b setfsgid 127 | 124 0x7c getsid 128 | 125 0x7d capget 129 | 126 0x7e capset 130 | 127 0x7f rt_sigpending 131 | 128 0x80 rt_sigtimedwait 132 | 129 0x81 rt_sigqueueinfo 133 | 130 0x82 rt_sigsuspend 134 | 131 0x83 sigaltstack 135 | 132 0x84 utime 136 | 133 0x85 mknod 137 | 134 0x86 uselib 138 | 135 0x87 personality 139 | 136 0x88 ustat 140 | 137 0x89 statfs 141 | 138 0x8a fstatfs 142 | 139 0x8b sysfs 143 | 140 0x8c getpriority 144 | 141 0x8d setpriority 145 | 142 0x8e sched_setparam 146 | 143 0x8f sched_getparam 147 | 144 0x90 sched_setscheduler 148 | 145 0x91 sched_getscheduler 149 | 146 0x92 sched_get_priority_max 150 | 147 0x93 sched_get_priority_min 151 | 148 0x94 sched_rr_get_interval 152 | 149 0x95 mlock 153 | 150 0x96 munlock 154 | 151 0x97 mlockall 155 | 152 0x98 munlockall 156 | 153 0x99 vhangup 157 | 154 0x9a modify_ldt 158 | 155 0x9b pivot_root 159 | 156 0x9c _sysctl 160 | 157 0x9d prctl 161 | 158 0x9e arch_prctl 162 | 159 0x9f adjtimex 163 | 160 0xa0 setrlimit 164 | 161 0xa1 chroot 165 | 162 0xa2 sync 166 | 163 0xa3 acct 167 | 164 0xa4 settimeofday 168 | 165 0xa5 mount 169 | 166 0xa6 umount2 170 | 167 0xa7 swapon 171 | 168 0xa8 swapoff 172 | 169 0xa9 reboot 173 | 170 0xaa sethostname 174 | 171 0xab setdomainname 175 | 172 0xac iopl 176 | 173 0xad ioperm 177 | 174 0xae create_module 178 | 175 0xaf init_module 179 | 176 0xb0 delete_module 180 | 177 0xb1 get_kernel_syms 181 | 178 0xb2 query_module 182 | 179 0xb3 quotactl 183 | 180 0xb4 nfsservctl 184 | 181 0xb5 getpmsg 185 | 182 0xb6 putpmsg 186 | 183 0xb7 afs_syscall 187 | 184 0xb8 tuxcall 188 | 185 0xb9 security 189 | 186 0xba gettid 190 | 187 0xbb readahead 191 | 188 0xbc setxattr 192 | 189 0xbd lsetxattr 193 | 190 0xbe fsetxattr 194 | 191 0xbf getxattr 195 | 192 0xc0 lgetxattr 196 | 193 0xc1 fgetxattr 197 | 194 0xc2 listxattr 198 | 195 0xc3 llistxattr 199 | 196 0xc4 flistxattr 200 | 197 0xc5 removexattr 201 | 198 0xc6 lremovexattr 202 | 199 0xc7 fremovexattr 203 | 200 0xc8 tkill 204 | 201 0xc9 time 205 | 202 0xca futex 206 | 203 0xcb sched_setaffinity 207 | 204 0xcc sched_getaffinity 208 | 205 0xcd set_thread_area 209 | 206 0xce io_setup 210 | 207 0xcf io_destroy 211 | 208 0xd0 io_getevents 212 | 209 0xd1 io_submit 213 | 210 0xd2 io_cancel 214 | 211 0xd3 get_thread_area 215 | 212 0xd4 lookup_dcookie 216 | 213 0xd5 epoll_create 217 | 214 0xd6 epoll_ctl_old 218 | 215 0xd7 epoll_wait_old 219 | 216 0xd8 remap_file_pages 220 | 217 0xd9 getdents64 221 | 218 0xda set_tid_address 222 | 219 0xdb restart_syscall 223 | 220 0xdc semtimedop 224 | 221 0xdd fadvise64 225 | 222 0xde timer_create 226 | 223 0xdf timer_settime 227 | 224 0xe0 timer_gettime 228 | 225 0xe1 timer_getoverrun 229 | 226 0xe2 timer_delete 230 | 227 0xe3 clock_settime 231 | 228 0xe4 clock_gettime 232 | 229 0xe5 clock_getres 233 | 230 0xe6 clock_nanosleep 234 | 231 0xe7 exit_group 235 | 232 0xe8 epoll_wait 236 | 233 0xe9 epoll_ctl 237 | 234 0xea tgkill 238 | 235 0xeb utimes 239 | 236 0xec vserver 240 | 237 0xed mbind 241 | 238 0xee set_mempolicy 242 | 239 0xef get_mempolicy 243 | 240 0xf0 mq_open 244 | 241 0xf1 mq_unlink 245 | 242 0xf2 mq_timedsend 246 | 243 0xf3 mq_timedreceive 247 | 244 0xf4 mq_notify 248 | 245 0xf5 mq_getsetattr 249 | 246 0xf6 kexec_load 250 | 247 0xf7 waitid 251 | 248 0xf8 add_key 252 | 249 0xf9 request_key 253 | 250 0xfa keyctl 254 | 251 0xfb ioprio_set 255 | 252 0xfc ioprio_get 256 | 253 0xfd inotify_init 257 | 254 0xfe inotify_add_watch 258 | 255 0xff inotify_rm_watch 259 | 256 0x100 migrate_pages 260 | 257 0x101 openat 261 | 258 0x102 mkdirat 262 | 259 0x103 mknodat 263 | 260 0x104 fchownat 264 | 261 0x105 futimesat 265 | 262 0x106 newfstatat 266 | 263 0x107 unlinkat 267 | 264 0x108 renameat 268 | 265 0x109 linkat 269 | 266 0x10a symlinkat 270 | 267 0x10b readlinkat 271 | 268 0x10c fchmodat 272 | 269 0x10d faccessat 273 | 270 0x10e pselect6 274 | 271 0x10f ppoll 275 | 272 0x110 unshare 276 | 273 0x111 set_robust_list 277 | 274 0x112 get_robust_list 278 | 275 0x113 splice 279 | 276 0x114 tee 280 | 277 0x115 sync_file_range 281 | 278 0x116 vmsplice 282 | 279 0x117 move_pages 283 | 280 0x118 utimensat 284 | 281 0x119 epoll_pwait 285 | 282 0x11a signalfd 286 | 283 0x11b timerfd_create 287 | 284 0x11c eventfd 288 | 285 0x11d fallocate 289 | 286 0x11e timerfd_settime 290 | 287 0x11f timerfd_gettime 291 | 288 0x120 accept4 292 | 289 0x121 signalfd4 293 | 290 0x122 eventfd2 294 | 291 0x123 epoll_create1 295 | 292 0x124 dup3 296 | 293 0x125 pipe2 297 | 294 0x126 inotify_init1 298 | 295 0x127 preadv 299 | 296 0x128 pwritev 300 | 297 0x129 rt_tgsigqueueinfo 301 | 298 0x12a perf_event_open 302 | 299 0x12b recvmmsg 303 | 300 0x12c fanotify_init 304 | 301 0x12d fanotify_mark 305 | 302 0x12e prlimit64 306 | 303 0x12f name_to_handle_at 307 | 304 0x130 open_by_handle_at 308 | 305 0x131 clock_adjtime 309 | 306 0x132 syncfs 310 | 307 0x133 sendmmsg 311 | 308 0x134 setns 312 | 309 0x135 getcpu 313 | 310 0x136 process_vm_readv 314 | 311 0x137 process_vm_writev 315 | 312 0x138 kcmp 316 | 313 0x139 finit_module 317 | 314 0x13a sched_setattr 318 | 315 0x13b sched_getattr 319 | 316 0x13c renameat2 320 | 317 0x13d seccomp 321 | 318 0x13e getrandom 322 | 319 0x13f memfd_create 323 | 320 0x140 kexec_file_load 324 | 321 0x141 bpf 325 | 322 0x142 execveat 326 | 323 0x143 userfaultfd 327 | 324 0x144 membarrier 328 | 325 0x145 mlock2 329 | 326 0x146 copy_file_range 330 | 327 0x147 preadv2 331 | 328 0x148 pwritev2 332 | 333 | \newpage 334 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: clean spellcheck docbook_fix_links 2 | 3 | OS := $(shell uname) 4 | ifeq ($(OS),Darwin) 5 | SHELL := "/bin/bash" 6 | ASPELLPATH := "/usr/local/bin/aspell" 7 | FONT := Palatino 8 | else 9 | ASPELLPATH := "/usr/bin/aspell" 10 | FONT := Noto Sans 11 | EPUB_FONTS := 'static/fonts/Noto*.ttf' 12 | endif 13 | 14 | ASPELL := $(shell { type $(ASPELLPATH); } 2>/dev/null) 15 | STYLE := $(shell { type /usr/bin/style; } 2>/dev/null) 16 | BUILD_DIR := "build" 17 | BOOK_CH1 := $(sort $(wildcard 01_*)) 18 | BOOK_CH2 := $(sort $(wildcard 02_*)) 19 | BOOK_CH3 := $(sort $(wildcard 03_*)) 20 | BOOK_CH4 := $(sort $(wildcard 04_*)) 21 | BOOK_CH5 := $(sort $(wildcard 05_*)) 22 | BOOK_CH6 := $(sort $(wildcard 06_*)) 23 | BOOK_CH_ALL := $(BOOK_CH1) $(BOOK_CH2) $(BOOK_CH3) $(BOOK_CH4) $(BOOK_CH4) $(BOOK_CH5) $(BOOK_CH6) 24 | 25 | PODIR := po 26 | BOOKNAME := sgos_handbook 27 | EMAIL := 'mckinney@subgraph.com' 28 | COPYRIGHT := Subgraph 29 | PACKAGE := 'Subgraph OS Handbook' 30 | VERSION := $(shell git describe --tags) 31 | POTHEADER:= --msgid-bugs-address $(EMAIL) --copyright-holder $(COPYRIGHT) --package-name $(PACKAGE) --package-version $(VERSION) 32 | HTMLOPTIONS:= --toc --highlight-style haddock --section-divs --number-sections --self-contained --css templates/sgos_handbook.css 33 | 34 | KERNEL_VERSION:=$(shell uname -r) 35 | LINUX_HEADERS:=/usr/src/linux-headers-$(KERNEL_VERSION) 36 | 37 | all: clean readability contents sgos_handbook 38 | pot_all: pot po4a_fixup 39 | docbook_debian: docbook docbook_fix_links 40 | docbook_dev: docbook_local docbook_fix_links_local 41 | 42 | # requires aspell, aspell-en 43 | spellcheck: 44 | ifdef ASPELL 45 | find . -maxdepth 1 -name "*.md" -exec $(ASPELLPATH) check {} \; 46 | else 47 | echo "$(ASPELLPATH) is missing -- no spellcheck possible" 48 | endif 49 | 50 | # requires diction 51 | readability: $(BUILD_DIR)/readability.txt 52 | $(BUILD_DIR)/readability.txt: $(BOOK_CH_ALL) 53 | ifdef STYLE 54 | style $^ > $@ 55 | else 56 | echo "/usr/bin/style is missing -- no readability check possible" 57 | endif 58 | 59 | # requires texlive, texlive-xetex, lmodern, pdftk 60 | contents: $(BUILD_DIR)/contents.pdf 61 | $(BUILD_DIR)/contents.pdf: $(BOOK_CH_ALL) metadata.yaml 62 | pandoc -r markdown -o $@ -H templates/style.tex --template=templates/sgos_handbook.latex --toc --highlight-style=haddock --latex-engine=xelatex -V mainfont="$(FONT)" $^ 63 | 64 | sgos_handbook: $(BUILD_DIR)/sgos_handbook.pdf 65 | $(BUILD_DIR)/sgos_handbook.pdf: static/sgos_handbook_cover.pdf build/contents.pdf 66 | pdftk $^ cat output $@ 67 | 68 | epub: $(BUILD_DIR)/sgos_handbook.epub 69 | $(BUILD_DIR)/sgos_handbook.epub: $(BOOK_CH_ALL) metadata.yaml 70 | pandoc -r markdown --epub-embed-font=$(EPUB_FONTS) --epub-cover-image=static/images/sgos_handbook_cover.png -o $@ $^ 71 | 72 | 73 | docbook: $(BUILD_DIR)/sgos_handbook.xml 74 | $(BUILD_DIR)/sgos_handbook.xml: $(BOOK_CH4) $(BOOK_CH5) metadata.yaml 75 | pandoc -s -r markdown -t docbook -o $@ $^ 76 | 77 | docbook_fix_links: 78 | sed -i 's/ $@ 94 | 95 | po4a_fixup: $(PODIR)/$(BOOKNAME)_fixed.pot 96 | $(PODIR)/$(BOOKNAME)_fixed.pot: $(PODIR)/$(BOOKNAME).pot 97 | awk -f scripts/po4a_fixup.awk $^ > $@ 98 | 99 | .PHONY: pot 100 | pot: $(PODIR)/$(BOOKNAME).pot 101 | 102 | $(PODIR)/$(BOOKNAME).pot: $(foreach chap,$(BOOK_CH_ALL), $(chap)) 103 | po4a-gettextize $(POTHEADER) -f text -M utf-8 $(foreach pot,$(BOOK_CH_ALL),-m $(pot)) -p $@ 104 | 105 | $(PODIR)/%.po: $(foreach chap,$(BOOK_CH_ALL), $(chap)) 106 | @po4a-updatepo $(POTHEADER) -f text -M -utf-8 $(foreach chap,$(BOOK_CH_ALL),-m $(chap)) -p $@ 107 | 108 | # This is a proof-of-concept as we don't have anything to translate. 109 | translate: 110 | po4a-translate -f text -M utf-8 -m $(PODIR)/$(BOOKNAME)_fixed.pot -p $(PODIR)/$(BOOKNAME)_fixed_fr.po -k 20 -l $(BOOKNAME)_fr.md 111 | 112 | # When we start doing real translations, they will be performed on 113 | # individual chapters and not a merged book. The code will look 114 | # # something like this: 115 | # $(foreach chap,$(BOOK_CH_ALL), po4a-translate -f text -M utf-8 -m $(chap) -p $(PODIR)/$*.po -k 20 -l $(shell basename -s .md $(chap))-$*.md ; ) 116 | 117 | clean: 118 | rm -f $(BUILD_DIR)/*.pdf $(BUILD_DIR)/*.txt 119 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Subgraph OS Handbook 2 | 3 | The Subgraph OS Handbook is a user guide for Subgraph OS, covering basic 4 | everyday uses as well as the advanced configuration. 5 | 6 | The Subgraph OS Handbook is written in Markdown. This is so that we can 7 | have a single source text that can be converted to multiple output formats, 8 | such as PDF, DocBook, Epub, and HTML. 9 | 10 | The goal of the Subgraph OS Handbook is to provide operating system 11 | documentation that is readable and translatable. The handbook is organized into 12 | sections for beginners and advanced users. 13 | 14 | The current roadmap for this project is the following: 15 | 16 | 1. Finish the document conversion framework 17 | 2. Add support for translation such that the single source text can be 18 | translated and localized versions of the handbook can be generated for each 19 | output type 20 | 3. Finish writing the content, adding graphics, etc. 21 | 4. Publish the finished handbook, including making it available in a Debian 22 | package for Subgraph OS, putting sections onto our website, etc. 23 | 24 | At this point, the next step will be to undertake having it translated into a 25 | few different languages. 26 | 27 | ## Pull requests 28 | 29 | The Subgraph OS Handbook is a work in progress. We will most likely not accept 30 | pull requests until the framework for generating the document and translation 31 | artifacts is complete and the text is mostly written. This is just to maintain 32 | consistency (ie: using the same voice throughout, ensuring the text meets the 33 | readability guidelines we are targetting, etc.). As the framework is not yet 34 | mature, the most important thing at this stage is that the document and 35 | translation artifacts build correctly. The bulk of the content is due to be 36 | added once the framework is mature. 37 | 38 | ## Building 39 | 40 | To build from source you will need to install at least the following build dependencies: 41 | 42 | ``` 43 | sudo apt install pdftk fonts-lmodern lmodern fig2ps make texlive-latex-recommended \ 44 | texlive-xetex texlive-latex-extra aspell aspell-en diction 45 | ``` 46 | -------------------------------------------------------------------------------- /build/.gitignore: -------------------------------------------------------------------------------- 1 | contents.pdf 2 | 3 | -------------------------------------------------------------------------------- /build/readability.txt: -------------------------------------------------------------------------------- 1 | readability grades: 2 | Kincaid: 8.9 3 | ARI: 9.6 4 | Coleman-Liau: 11.7 5 | Flesch Index: 57.2/100 6 | Fog Index: 11.6 7 | Lix: 44.8 = school year 8 8 | SMOG-Grading: 10.9 9 | sentence info: 10 | 55671 characters 11 | 11079 words, average length 5.02 characters = 1.59 syllables 12 | 757 sentences, average length 14.6 words 13 | 35% (268) short sentences (at most 10 words) 14 | 7% (53) long sentences (at least 25 words) 15 | 293 paragraphs, average length 2.6 sentences 16 | 0% (3) questions 17 | 43% (327) passive sentences 18 | longest sent 65 wds at sent 396; shortest sent 1 wds at sent 57 19 | word usage: 20 | verb types: 21 | to be (387) auxiliary (267) 22 | types as % of total: 23 | conjunctions 4% (401) pronouns 7% (736) prepositions 10% (1144) 24 | nominalizations 2% (250) 25 | sentence beginnings: 26 | pronoun (155) interrogative pronoun (28) article (95) 27 | subordinating conjunction (46) conjunction (1) preposition (53) 28 | -------------------------------------------------------------------------------- /build/sgos_handbook.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/build/sgos_handbook.pdf -------------------------------------------------------------------------------- /metadata.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Subgraph OS Handbook" 3 | documentclass: [book,scrartcl,table] 4 | --- 5 | -------------------------------------------------------------------------------- /scripts/po4a_fixup.awk: -------------------------------------------------------------------------------- 1 | # This script is run after po4a-gettextive to remove any entries that contain 2 | # Markdown or LaTeX directives that should not be translated 3 | 4 | BEGIN { 5 | RS = "#. type:" ; 6 | FS = "\n" ; 7 | ORS = ""; 8 | } 9 | 10 | # This code will retain only the records that do not match the Markdown and 11 | # LaTeX directives we specify in the regular expressions below 12 | 13 | !/msgid "\\\\newpage"/ && \ 14 | !/msgid "\\\\clearpage"/ && \ 15 | !/msgid "!\[.+\]\(.+.png\)"/ \ 16 | { 17 | # We print the #. type: row for every record past the first 18 | if (NR>1) { 19 | print RS$0 20 | } else { 21 | print $0 22 | } 23 | } 24 | 25 | -------------------------------------------------------------------------------- /scripts/syscall_table.awk: -------------------------------------------------------------------------------- 1 | #!/bin/awk -f 2 | 3 | BEGIN { 4 | printf("Syscall(dec) Syscall(hex) System Call\n"); 5 | sep = sprintf("%*s",12," "); 6 | gsub(/ /, "-",sep); 7 | printf("%s %s %s\n", sep, sep, sep) 8 | } 9 | 10 | { 11 | if ($2 ~ "__NR_") { 12 | gsub(/__NR_/,"",$2); 13 | printf ("%-12d 0x%-12x%-12s\n", $3, $3, $2) 14 | } 15 | } 16 | 17 | END { 18 | print("\n\\newpage") 19 | } 20 | -------------------------------------------------------------------------------- /static/fonts/NotoSans-Bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/fonts/NotoSans-Bold.ttf -------------------------------------------------------------------------------- /static/fonts/NotoSans-BoldItalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/fonts/NotoSans-BoldItalic.ttf -------------------------------------------------------------------------------- /static/fonts/NotoSans-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/fonts/NotoSans-Regular.ttf -------------------------------------------------------------------------------- /static/images/CoyIM_account_details_basic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/CoyIM_account_details_basic.png -------------------------------------------------------------------------------- /static/images/CoyIM_configure_master_password.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/CoyIM_configure_master_password.png -------------------------------------------------------------------------------- /static/images/CoyIM_connected.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/CoyIM_connected.png -------------------------------------------------------------------------------- /static/images/CoyIM_encrypt_config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/CoyIM_encrypt_config.png -------------------------------------------------------------------------------- /static/images/Gnome_Disks_dialog_format.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Gnome_Disks_dialog_format.png -------------------------------------------------------------------------------- /static/images/Gnome_Disks_dialog_restore.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Gnome_Disks_dialog_restore.png -------------------------------------------------------------------------------- /static/images/Gnome_Disks_menu_format.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Gnome_Disks_menu_format.png -------------------------------------------------------------------------------- /static/images/Gnome_Disks_menu_restore.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Gnome_Disks_menu_restore.png -------------------------------------------------------------------------------- /static/images/Gnome_Disks_select.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Gnome_Disks_select.png -------------------------------------------------------------------------------- /static/images/OnionShare_TorBrowser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/OnionShare_TorBrowser.png -------------------------------------------------------------------------------- /static/images/OnionShare_onionshare-gui.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/OnionShare_onionshare-gui.png -------------------------------------------------------------------------------- /static/images/OnionShare_select_file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/OnionShare_select_file.png -------------------------------------------------------------------------------- /static/images/Oz_menu_addfiles_pdf.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Oz_menu_addfiles_pdf.png -------------------------------------------------------------------------------- /static/images/Oz_menu_addfiles_pdf_prompt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Oz_menu_addfiles_pdf_prompt.png -------------------------------------------------------------------------------- /static/images/Ricochet_add_contact.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Ricochet_add_contact.png -------------------------------------------------------------------------------- /static/images/Ricochet_chatting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Ricochet_chatting.png -------------------------------------------------------------------------------- /static/images/Subgraph_Firewall_alert.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Subgraph_Firewall_alert.png -------------------------------------------------------------------------------- /static/images/Subgraph_Firewall_edit_rule.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Subgraph_Firewall_edit_rule.png -------------------------------------------------------------------------------- /static/images/Subgraph_Firewall_menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Subgraph_Firewall_menu.png -------------------------------------------------------------------------------- /static/images/Subgraph_Firewall_options.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Subgraph_Firewall_options.png -------------------------------------------------------------------------------- /static/images/Subgraph_Firewall_settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/Subgraph_Firewall_settings.png -------------------------------------------------------------------------------- /static/images/oz_menu_addfiles_menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/oz_menu_addfiles_menu.png -------------------------------------------------------------------------------- /static/images/oz_menu_addfiles_prompt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/oz_menu_addfiles_prompt.png -------------------------------------------------------------------------------- /static/images/oz_menu_zebra.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/oz_menu_zebra.png -------------------------------------------------------------------------------- /static/images/sgos.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/sgos.png -------------------------------------------------------------------------------- /static/images/sgos_handbook_cover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/sgos_handbook_cover.png -------------------------------------------------------------------------------- /static/images/subgraph_splash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/subgraph_splash.png -------------------------------------------------------------------------------- /static/images/virt-manager_00_firtlaunch_delete.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_00_firtlaunch_delete.png -------------------------------------------------------------------------------- /static/images/virt-manager_00_firtlaunch_error.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_00_firtlaunch_error.png -------------------------------------------------------------------------------- /static/images/virt-manager_00_hypervisor_select.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_00_hypervisor_select.png -------------------------------------------------------------------------------- /static/images/virt-manager_00_virtman_ready.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_00_virtman_ready.png -------------------------------------------------------------------------------- /static/images/virt-manager_01_browser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_01_browser.png -------------------------------------------------------------------------------- /static/images/virt-manager_01_cpuram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_01_cpuram.png -------------------------------------------------------------------------------- /static/images/virt-manager_01_createnew.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_01_createnew.png -------------------------------------------------------------------------------- /static/images/virt-manager_01_diskimage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_01_diskimage.png -------------------------------------------------------------------------------- /static/images/virt-manager_01_done.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_01_done.png -------------------------------------------------------------------------------- /static/images/virt-manager_01_name.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/images/virt-manager_01_name.png -------------------------------------------------------------------------------- /static/sgos_handbook_cover.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/subgraph/sgos_handbook/e307251d825619928da26b6648302f945624698b/static/sgos_handbook_cover.pdf -------------------------------------------------------------------------------- /subgraph-os-help.desktop: -------------------------------------------------------------------------------- 1 | [Desktop Entry] 2 | Type=Application 3 | Version=1.0 4 | Name=Subgraph OS Help 5 | GenericName=Help browser for Subgraph OS 6 | TryExec=yelp 7 | Exec=yelp /usr/share/sgos-handbook/docbook/en-US/sgos_handbook.xml 8 | Comment=Subgraph OS Help 9 | Icon=help-browser 10 | Terminal=false 11 | StartupNotify=true 12 | MimeType=x-scheme-handler/ghelp;x-scheme-handler/help;x-scheme-handler/info;x-scheme-handler/man; 13 | Categories=GNOME;GTK;Core;Documentation;Utility; 14 | -------------------------------------------------------------------------------- /templates/default.latex: -------------------------------------------------------------------------------- 1 | \documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$$if(papersize)$$papersize$,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{$documentclass$} 2 | $if(fontfamily)$ 3 | \usepackage{$fontfamily$} 4 | $else$ 5 | \usepackage{lmodern} 6 | $endif$ 7 | $if(linestretch)$ 8 | \usepackage{setspace} 9 | \setstretch{$linestretch$} 10 | $endif$ 11 | \usepackage{amssymb,amsmath} 12 | \usepackage{ifxetex,ifluatex} 13 | \usepackage{fixltx2e} % provides \textsubscript 14 | \ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex 15 | \usepackage[T1]{fontenc} 16 | \usepackage[utf8]{inputenc} 17 | $if(euro)$ 18 | \usepackage{eurosym} 19 | $endif$ 20 | \else % if luatex or xelatex 21 | \ifxetex 22 | \usepackage{mathspec} 23 | \usepackage{xltxtra,xunicode} 24 | \else 25 | \usepackage{fontspec} 26 | \fi 27 | \defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase} 28 | \newcommand{\euro}{€} 29 | $if(mainfont)$ 30 | \setmainfont{$mainfont$} 31 | $endif$ 32 | $if(sansfont)$ 33 | \setsansfont{$sansfont$} 34 | $endif$ 35 | $if(monofont)$ 36 | \setmonofont[Mapping=tex-ansi]{$monofont$} 37 | $endif$ 38 | $if(mathfont)$ 39 | \setmathfont(Digits,Latin,Greek){$mathfont$} 40 | $endif$ 41 | $if(CJKmainfont)$ 42 | \usepackage{xeCJK} 43 | \setCJKmainfont[$CJKoptions$]{$CJKmainfont$} 44 | $endif$ 45 | \fi 46 | % use upquote if available, for straight quotes in verbatim environments 47 | \IfFileExists{upquote.sty}{\usepackage{upquote}}{} 48 | % use microtype if available 49 | \IfFileExists{microtype.sty}{% 50 | \usepackage{microtype} 51 | \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts 52 | }{} 53 | $if(geometry)$ 54 | \usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry} 55 | $endif$ 56 | \ifxetex 57 | \usepackage[setpagesize=false, % page size defined by xetex 58 | unicode=false, % unicode breaks when used with xetex 59 | xetex]{hyperref} 60 | \else 61 | \usepackage[unicode=true]{hyperref} 62 | \fi 63 | \usepackage[usenames,dvipsnames]{color} 64 | \hypersetup{breaklinks=true, 65 | bookmarks=true, 66 | pdfauthor={$author-meta$}, 67 | pdftitle={$title-meta$}, 68 | colorlinks=true, 69 | citecolor=$if(citecolor)$$citecolor$$else$blue$endif$, 70 | urlcolor=$if(urlcolor)$$urlcolor$$else$blue$endif$, 71 | linkcolor=$if(linkcolor)$$linkcolor$$else$magenta$endif$, 72 | pdfborder={0 0 0}} 73 | \urlstyle{same} % don't use monospace font for urls 74 | $if(lang)$ 75 | \ifxetex 76 | \usepackage{polyglossia} 77 | \setmainlanguage{$mainlang$} 78 | \setotherlanguages{$for(otherlang)$$otherlang$$sep$,$endfor$} 79 | \else 80 | \usepackage[shorthands=off,$lang$]{babel} 81 | \fi 82 | $endif$ 83 | $if(natbib)$ 84 | \usepackage{natbib} 85 | \bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} 86 | $endif$ 87 | $if(biblatex)$ 88 | \usepackage{biblatex} 89 | $for(bibliography)$ 90 | \addbibresource{$bibliography$} 91 | $endfor$ 92 | $endif$ 93 | $if(listings)$ 94 | \usepackage{listings} 95 | $endif$ 96 | $if(lhs)$ 97 | \lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} 98 | $endif$ 99 | $if(highlighting-macros)$ 100 | $highlighting-macros$ 101 | $endif$ 102 | $if(verbatim-in-note)$ 103 | \usepackage{fancyvrb} 104 | \VerbatimFootnotes 105 | $endif$ 106 | $if(tables)$ 107 | \usepackage{longtable,booktabs} 108 | $endif$ 109 | $if(graphics)$ 110 | \usepackage{graphicx,grffile} 111 | \makeatletter 112 | \def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} 113 | \def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} 114 | \makeatother 115 | % Scale images if necessary, so that they will not overflow the page 116 | % margins by default, and it is still possible to overwrite the defaults 117 | % using explicit options in \includegraphics[width, height, ...]{} 118 | \setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} 119 | $endif$ 120 | $if(links-as-notes)$ 121 | % Make links footnotes instead of hotlinks: 122 | \renewcommand{\href}[2]{#2\footnote{\url{#1}}} 123 | $endif$ 124 | $if(strikeout)$ 125 | \usepackage[normalem]{ulem} 126 | % avoid problems with \sout in headers with hyperref: 127 | \pdfstringdefDisableCommands{\renewcommand{\sout}{}} 128 | $endif$ 129 | \setlength{\parindent}{0pt} 130 | \setlength{\parskip}{6pt plus 2pt minus 1pt} 131 | \setlength{\emergencystretch}{3em} % prevent overfull lines 132 | \providecommand{\tightlist}{% 133 | \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} 134 | $if(numbersections)$ 135 | \setcounter{secnumdepth}{5} 136 | $else$ 137 | \setcounter{secnumdepth}{0} 138 | $endif$ 139 | $if(verbatim-in-note)$ 140 | \VerbatimFootnotes % allows verbatim text in footnotes 141 | $endif$ 142 | 143 | $if(title)$ 144 | \title{$title$$if(subtitle)$\\\vspace{0.5em}{\large $subtitle$}$endif$} 145 | $endif$ 146 | $if(author)$ 147 | \author{$for(author)$$author$$sep$ \and $endfor$} 148 | $endif$ 149 | \date{$date$} 150 | $for(header-includes)$ 151 | $header-includes$ 152 | $endfor$ 153 | 154 | % Redefines (sub)paragraphs to behave more like sections 155 | \ifx\paragraph\undefined\else 156 | \let\oldparagraph\paragraph 157 | \renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} 158 | \fi 159 | \ifx\subparagraph\undefined\else 160 | \let\oldsubparagraph\subparagraph 161 | \renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} 162 | \fi 163 | 164 | \begin{document} 165 | $if(title)$ 166 | \maketitle 167 | $endif$ 168 | $if(abstract)$ 169 | \begin{abstract} 170 | $abstract$ 171 | \end{abstract} 172 | $endif$ 173 | 174 | $for(include-before)$ 175 | $include-before$ 176 | 177 | $endfor$ 178 | $if(toc)$ 179 | { 180 | \hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$black$endif$} 181 | \setcounter{tocdepth}{$toc-depth$} 182 | \tableofcontents 183 | } 184 | $endif$ 185 | $if(lot)$ 186 | \listoftables 187 | $endif$ 188 | $if(lof)$ 189 | \listoffigures 190 | $endif$ 191 | $body$ 192 | 193 | $if(natbib)$ 194 | $if(bibliography)$ 195 | $if(biblio-title)$ 196 | $if(book-class)$ 197 | \renewcommand\bibname{$biblio-title$} 198 | $else$ 199 | \renewcommand\refname{$biblio-title$} 200 | $endif$ 201 | $endif$ 202 | \bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} 203 | 204 | $endif$ 205 | $endif$ 206 | $if(biblatex)$ 207 | \printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$ 208 | 209 | $endif$ 210 | $for(include-after)$ 211 | $include-after$ 212 | 213 | $endfor$ 214 | \end{document} 215 | -------------------------------------------------------------------------------- /templates/sgos_handbook.css: -------------------------------------------------------------------------------- 1 | img { 2 | max-width: 100%; 3 | height: auto; 4 | } 5 | 6 | blockquote { 7 | background: #d9d9ff; 8 | border-left: 1px dashed #ccc; 9 | margin: 30px; 10 | padding: 30px; 11 | } 12 | 13 | body { 14 | padding-top: 0px !important; 15 | color: rgb(100, 100, 100); 16 | font-style: normal; 17 | font-family: 'Noto Sans','Lato',sans-serif !important; 18 | } 19 | 20 | pre { 21 | margin-left: 1em; 22 | margin-right: 1em; 23 | } 24 | 25 | table { 26 | border-collapse: collapse; 27 | border: 1px solid; 28 | } 29 | 30 | th { 31 | border: 2px solid; 32 | padding:10px; 33 | background: #d9d9ff; 34 | } 35 | 36 | td { 37 | border: 1px dotted black; 38 | padding:15px; 39 | width:100px; 40 | } 41 | 42 | tr:nth-child(even) { 43 | background-color: #f1f1f1; 44 | } 45 | 46 | 47 | tr:nth-child(odd) { 48 | background-color: #ffffff; 49 | } 50 | -------------------------------------------------------------------------------- /templates/sgos_handbook.latex: -------------------------------------------------------------------------------- 1 | \documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$$if(papersize)$$papersize$,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{$documentclass$} 2 | $if(fontfamily)$ 3 | \usepackage{$fontfamily$} 4 | $else$ 5 | \usepackage{lmodern} 6 | $endif$ 7 | $if(linestretch)$ 8 | \usepackage{setspace} 9 | \setstretch{$linestretch$} 10 | $endif$ 11 | \usepackage{amssymb,amsmath} 12 | \usepackage{ifxetex,ifluatex} 13 | \usepackage{fixltx2e} % provides \textsubscript 14 | \ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex 15 | \usepackage[T1]{fontenc} 16 | \usepackage[utf8]{inputenc} 17 | $if(euro)$ 18 | \usepackage{eurosym} 19 | $endif$ 20 | \else % if luatex or xelatex 21 | \ifxetex 22 | \usepackage{mathspec} 23 | \usepackage{xltxtra,xunicode} 24 | \else 25 | \usepackage{fontspec} 26 | \fi 27 | \defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase} 28 | \newcommand{\euro}{€} 29 | $if(mainfont)$ 30 | \setmainfont{$mainfont$} 31 | $endif$ 32 | $if(sansfont)$ 33 | \setsansfont{$sansfont$} 34 | $endif$ 35 | $if(monofont)$ 36 | \setmonofont[Mapping=tex-ansi]{$monofont$} 37 | $endif$ 38 | $if(mathfont)$ 39 | \setmathfont(Digits,Latin,Greek){$mathfont$} 40 | $endif$ 41 | $if(CJKmainfont)$ 42 | \usepackage{xeCJK} 43 | \setCJKmainfont[$CJKoptions$]{$CJKmainfont$} 44 | $endif$ 45 | \fi 46 | % use upquote if available, for straight quotes in verbatim environments 47 | \IfFileExists{upquote.sty}{\usepackage{upquote}}{} 48 | % use microtype if available 49 | \IfFileExists{microtype.sty}{% 50 | \usepackage{microtype} 51 | \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts 52 | }{} 53 | $if(geometry)$ 54 | \usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry} 55 | $endif$ 56 | \ifxetex 57 | \usepackage[setpagesize=false, % page size defined by xetex 58 | unicode=false, % unicode breaks when used with xetex 59 | xetex]{hyperref} 60 | \else 61 | \usepackage[unicode=true]{hyperref} 62 | \fi 63 | \usepackage[usenames,dvipsnames]{color} 64 | \hypersetup{breaklinks=true, 65 | bookmarks=true, 66 | pdfauthor={$author-meta$}, 67 | pdftitle={$title-meta$}, 68 | colorlinks=true, 69 | citecolor=$if(citecolor)$$citecolor$$else$blue$endif$, 70 | urlcolor=$if(urlcolor)$$urlcolor$$else$blue$endif$, 71 | linkcolor=$if(linkcolor)$$linkcolor$$else$magenta$endif$, 72 | pdfborder={0 0 0}} 73 | \urlstyle{same} % don't use monospace font for urls 74 | $if(lang)$ 75 | \ifxetex 76 | \usepackage{polyglossia} 77 | \setmainlanguage{$mainlang$} 78 | \setotherlanguages{$for(otherlang)$$otherlang$$sep$,$endfor$} 79 | \else 80 | \usepackage[shorthands=off,$lang$]{babel} 81 | \fi 82 | $endif$ 83 | $if(natbib)$ 84 | \usepackage{natbib} 85 | \bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} 86 | $endif$ 87 | $if(biblatex)$ 88 | \usepackage{biblatex} 89 | $for(bibliography)$ 90 | \addbibresource{$bibliography$} 91 | $endfor$ 92 | $endif$ 93 | $if(listings)$ 94 | \usepackage{listings} 95 | $endif$ 96 | $if(lhs)$ 97 | \lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} 98 | $endif$ 99 | $if(highlighting-macros)$ 100 | $highlighting-macros$ 101 | $endif$ 102 | $if(verbatim-in-note)$ 103 | \usepackage{fancyvrb} 104 | \VerbatimFootnotes 105 | $endif$ 106 | $if(tables)$ 107 | \usepackage{longtable,booktabs} 108 | $endif$ 109 | $if(graphics)$ 110 | \usepackage{graphicx,grffile} 111 | \makeatletter 112 | \def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} 113 | \def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} 114 | \makeatother 115 | % Scale images if necessary, so that they will not overflow the page 116 | % margins by default, and it is still possible to overwrite the defaults 117 | % using explicit options in \includegraphics[width, height, ...]{} 118 | \setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} 119 | $endif$ 120 | $if(links-as-notes)$ 121 | % Make links footnotes instead of hotlinks: 122 | \renewcommand{\href}[2]{#2\footnote{\url{#1}}} 123 | $endif$ 124 | $if(strikeout)$ 125 | \usepackage[normalem]{ulem} 126 | % avoid problems with \sout in headers with hyperref: 127 | \pdfstringdefDisableCommands{\renewcommand{\sout}{}} 128 | $endif$ 129 | \setlength{\parindent}{0pt} 130 | \setlength{\parskip}{6pt plus 2pt minus 1pt} 131 | \setlength{\emergencystretch}{3em} % prevent overfull lines 132 | \providecommand{\tightlist}{% 133 | \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} 134 | $if(numbersections)$ 135 | \setcounter{secnumdepth}{5} 136 | $else$ 137 | \setcounter{secnumdepth}{0} 138 | $endif$ 139 | $if(verbatim-in-note)$ 140 | \VerbatimFootnotes % allows verbatim text in footnotes 141 | $endif$ 142 | 143 | $if(title)$ 144 | \title{$title$$if(subtitle)$\\\vspace{0.5em}{\large $subtitle$}$endif$} 145 | $endif$ 146 | $if(author)$ 147 | \author{$for(author)$$author$$sep$ \and $endfor$} 148 | $endif$ 149 | \date{$date$} 150 | $for(header-includes)$ 151 | $header-includes$ 152 | $endfor$ 153 | 154 | % Redefines (sub)paragraphs to behave more like sections 155 | \ifx\paragraph\undefined\else 156 | \let\oldparagraph\paragraph 157 | \renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} 158 | \fi 159 | \ifx\subparagraph\undefined\else 160 | \let\oldsubparagraph\subparagraph 161 | \renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} 162 | \fi 163 | 164 | \begin{document} 165 | $if(title)$ 166 | \maketitle 167 | $endif$ 168 | $if(abstract)$ 169 | \begin{abstract} 170 | $abstract$ 171 | \end{abstract} 172 | $endif$ 173 | 174 | $for(include-before)$ 175 | $include-before$ 176 | 177 | $endfor$ 178 | $if(toc)$ 179 | { 180 | \hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$black$endif$} 181 | \setcounter{tocdepth}{$toc-depth$} 182 | \tableofcontents 183 | } 184 | $endif$ 185 | $if(lot)$ 186 | \listoftables 187 | $endif$ 188 | $if(lof)$ 189 | \listoffigures 190 | $endif$ 191 | $body$ 192 | 193 | $if(natbib)$ 194 | $if(bibliography)$ 195 | $if(biblio-title)$ 196 | $if(book-class)$ 197 | \renewcommand\bibname{$biblio-title$} 198 | $else$ 199 | \renewcommand\refname{$biblio-title$} 200 | $endif$ 201 | $endif$ 202 | \bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} 203 | 204 | $endif$ 205 | $endif$ 206 | $if(biblatex)$ 207 | \printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$ 208 | 209 | $endif$ 210 | $for(include-after)$ 211 | $include-after$ 212 | 213 | $endfor$ 214 | \end{document} 215 | -------------------------------------------------------------------------------- /templates/sgos_handbook_epub.css: -------------------------------------------------------------------------------- 1 | @font-face { 2 | font-family: NotoSans; 3 | font-style: normal; 4 | font-weight: normal; 5 | src:url("NotoSans-Regular.ttf"); 6 | } 7 | @font-face { 8 | font-family: NotoSans; 9 | font-style: normal; 10 | font-weight: bold; 11 | src:url("NotoSans-Bold.ttf"); 12 | } 13 | @font-face { 14 | font-family: NotoSans; 15 | font-style: italic; 16 | font-weight: normal; 17 | src:url("NotoSans-Italic.ttf"); 18 | } 19 | @font-face { 20 | font-family: NotoSans; 21 | font-style: italic; 22 | font-weight: bold; 23 | src:url("NotoSans-BoldItalic.ttf"); 24 | } 25 | body { font-family: "Noto Sans"; } 26 | 27 | -------------------------------------------------------------------------------- /templates/style.tex: -------------------------------------------------------------------------------- 1 | \usepackage{framed} 2 | \usepackage{xcolor} 3 | \let\oldquote=\quote 4 | \let\endoldquote=\endquote 5 | \colorlet{shadecolor}{blue!15} 6 | \renewenvironment{quote}{\begin{shaded*}\begin{oldquote}}{\end{oldquote}\end{shaded*}} 7 | \pagestyle{myheadings} 8 | 9 | --------------------------------------------------------------------------------