diff --git a/.gitignore b/.gitignore index c75eecc..8550c4d 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /public +.direnv diff --git a/LICENSE.md b/LICENSE.md index 06af4d1..0ad7de3 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,4 @@ -Copyright 2023 Clan contributers +Copyright 2023 cLAN contributers Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: diff --git a/config.toml b/config.toml index 9dc23a0..998ca89 100644 --- a/config.toml +++ b/config.toml @@ -1,6 +1,6 @@ # The URL the site will be built for base_url = "https://clan.lol" -title = "Clan" +title = "cLAN" # The site theme to use. theme = "adidoks" @@ -44,7 +44,7 @@ highlight_code = true [extra] # Put all your custom variables here -author = "Clan contributors" +author = "cLAN contributors" email = "admin@clan.lol" # If running on netlify.app site, set to true @@ -58,7 +58,7 @@ theme_color = "#fff" # More about site's title title_separator = "-" # set as |, -, _, etc -title_addition = "Build your own cLan" +title_addition = "Build your own cLAN" # Set date format in blog publish metadata @@ -122,6 +122,6 @@ url = "/privacy-policy/" weight = 10 [[extra.footer.nav]] -name = "Code of Conduct" -url = "/docs/contributing/code-of-conduct/" +name = "Overview" +url = "/docs/overview" weight = 20 diff --git a/content/_index.md b/content/_index.md index 00e1491..cb8c988 100644 --- a/content/_index.md +++ b/content/_index.md @@ -3,10 +3,10 @@ title = "Build your own" # The homepage contents [extra] -lead = 'cLan logo
cLan envisions a new model for a decentralized network, designed to provide families, smaller groups, and small businesses a platform thatโ€™s private, secure, and user-friendly. ' +lead = 'cLAN logo
cLAN envisions a new model for a decentralized network, designed to provide families, smaller groups, and small businesses a platform thatโ€™s private, secure, and user-friendly. ' url = "/docs/getting-started/introduction/" url_button = "Learn more" -repo_version = "Clan v0.0.0-alpha" +repo_version = "cLAN v0.0.0-alpha" repo_license = "Open-source MIT License." repo_url = "https://git.clan.lol/clan/" @@ -14,7 +14,7 @@ repo_url = "https://git.clan.lol/clan/" [[extra.menu.main]] name = "Docs" section = "docs" -url = "/docs/getting-started/introduction/" +url = "/docs/overview" weight = 10 [[extra.menu.main]] @@ -25,13 +25,13 @@ weight = 20 [[extra.list]] title = "Easy to use" -content = 'cLan provides a user-friendly interface that allows you to establish your own private network, complete with services.' +content = 'cLAN provides a user-friendly interface that allows you to establish your own private network, complete with services.' [[extra.list]] title = "Open-source" -content = 'All code for cLan is freely available and open-source.' +content = 'All code for cLAN is freely available and open-source.' [[extra.list]] title = "Decentralized" -content = "The design of cLan enables the distribution of your applications/services across several machines. This increases the resilience of the network, ensuring continued operation even if some computers become unavailable." +content = "The design of cLAN enables the distribution of your applications/services across several machines. This increases the resilience of the network, ensuring continued operation even if some computers become unavailable." +++ diff --git a/content/authors/Mic92.md b/content/authors/Mic92.md index e401ee0..308e6d0 100644 --- a/content/authors/Mic92.md +++ b/content/authors/Mic92.md @@ -1,6 +1,6 @@ +++ title = "Mic92" -description = "Contributor to Clan." +description = "Contributor to cLAN." date = 2021-04-01T08:50:45+00:00 updated = 2021-04-01T08:50:45+00:00 draft = false diff --git a/content/blog/hello-world.md b/content/blog/hello-world.md index 7956c1a..6ba0c8f 100644 --- a/content/blog/hello-world.md +++ b/content/blog/hello-world.md @@ -1,6 +1,6 @@ +++ title = "Hello World" -description = "Introducing Clan, a new model for a decentralized network, designed to provide families, smaller groups, and small businesses a platform thatโ€™s private, secure, and user-friendly." +description = "Introducing cLAN, a new model for a decentralized network, designed to provide families, smaller groups, and small businesses a platform thatโ€™s private, secure, and user-friendly." date = 2021-05-01T09:19:42+00:00 updated = 2021-05-01T09:19:42+00:00 draft = false diff --git a/content/docs/contributing/_index.md b/content/docs/contributing/_index.md index 0b29bd2..7695e10 100644 --- a/content/docs/contributing/_index.md +++ b/content/docs/contributing/_index.md @@ -1,6 +1,6 @@ +++ title = "Contributing" -description = "Find out how to contribute to Clan." +description = "Find out how to contribute to cLAN." date = 2025-05-01T18:00:00+00:00 updated = 2021-05-01T18:00:00+00:00 template = "docs/section.html" diff --git a/content/docs/contributing/code-of-conduct.md b/content/docs/contributing/code-of-conduct.md deleted file mode 100644 index f212db1..0000000 --- a/content/docs/contributing/code-of-conduct.md +++ /dev/null @@ -1,146 +0,0 @@ -+++ -title = "Code of Conduct" -description = "Contributor Covenant Code of Conduct." -date = 2021-05-01T18:20:00+00:00 -updated = 2021-05-01T18:20:00+00:00 -draft = false -weight = 420 -sort_by = "weight" -template = "docs/page.html" - -[extra] -lead = "Contributor Covenant Code of Conduct." -toc = true -top = false -+++ - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available -at [https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations diff --git a/content/docs/contributing/how-to-contribute.md b/content/docs/contributing/how-to-contribute.md index 7bbea15..fa2f193 100644 --- a/content/docs/contributing/how-to-contribute.md +++ b/content/docs/contributing/how-to-contribute.md @@ -1,6 +1,6 @@ +++ title = "How to Contribute" -description = "Contribute to Clan, improve documentation, or submit to showcase." +description = "Contribute to cLAN, improve documentation, or submit to showcase." date = 2021-05-01T18:10:00+00:00 updated = 2021-05-01T18:10:00+00:00 draft = false @@ -9,22 +9,18 @@ sort_by = "weight" template = "docs/page.html" [extra] -lead = "Contribute to Clan, improve documentation, or submit to showcase." +lead = "Contribute to cLAN, improve documentation, or submit to showcase." toc = true top = false +++ -๐Ÿ‘‰ Make sure to read the [Code of Conduct](../code-of-conduct/). +## Contribute -## Contribute to Doks +๐Ÿ‘‰ Explore our repos at [git.clan.lol](https://git.clan.lol/explore/repos) -๐Ÿ‘‰ The Clan code lives in the [`clan` repository](https://git.clan.lol/clan/clan) +๐Ÿ‘‰ [Create issues here](https://git.clan.lol/issues) -### Create an issue -- +## Improve these docs -## Improve documentation - -๐Ÿ‘‰ The documentation lives in [`./docs/`](https://git.clan.lol/clan/clan/docs) -of the [`clan` repository](https://git.clan.lol/clan/clan/docs). +๐Ÿ‘‰ The documentation lives in [git.clan.lol/clan/clan-homepage](https://git.clan.lol/clan/clan-homepage/src/branch/main/content/docs) diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md deleted file mode 100644 index 8b972db..0000000 --- a/content/docs/getting-started/_index.md +++ /dev/null @@ -1,10 +0,0 @@ -+++ -title = "Getting Started" -description = "Quick start and guides for installing the AdiDoks theme on your preferred operating system." -date = 2025-05-01T08:00:00+00:00 -updated = 2021-05-01T08:00:00+00:00 -template = "docs/section.html" -sort_by = "weight" -weight = 1 -draft = false -+++ diff --git a/content/docs/getting-started/introduction.md b/content/docs/getting-started/introduction.md deleted file mode 100644 index 6dfe20b..0000000 --- a/content/docs/getting-started/introduction.md +++ /dev/null @@ -1,31 +0,0 @@ -+++ -title = "Introduction" -description = "AdiDoks is a Zola theme helping you build modern documentation websites, which is a port of the Hugo theme Doks for Zola." -date = 2021-05-01T08:00:00+00:00 -updated = 2021-05-01T08:00:00+00:00 -draft = false -weight = 10 -sort_by = "weight" -template = "docs/page.html" - -[extra] -lead = 'AdiDoks is a Zola theme helping you build modern documentation websites, which is a port of the Hugo theme Doks for Zola.' -toc = true -top = false -+++ - -## Quick Start - -One page summary of how to start a new AdiDoks project. [Quick Start โ†’](../quick-start/) - -## Go further - -Contributing and Help. - -## Contributing - -Find out how to contribute to Doks. [Contributing โ†’](../../contributing/how-to-contribute/) - -## Help - -Get help on Doks. [Help โ†’](../../help/faq/) diff --git a/content/docs/getting-started/quick-start.md b/content/docs/getting-started/quick-start.md deleted file mode 100644 index db3a22d..0000000 --- a/content/docs/getting-started/quick-start.md +++ /dev/null @@ -1,94 +0,0 @@ -+++ -title = "Quick Start" -description = "One page summary of how to start a new AdiDoks project." -date = 2021-05-01T08:20:00+00:00 -updated = 2021-05-01T08:20:00+00:00 -draft = false -weight = 20 -sort_by = "weight" -template = "docs/page.html" - -[extra] -lead = "One page summary of how to start a new AdiDoks project." -toc = true -top = false -+++ - -## Requirements - -Before using the theme, you need to install the [Zola](https://www.getzola.org/documentation/getting-started/installation/) โ‰ฅ 0.15.0. - -## Run the Theme Directly - -```bash -git clone https://github.com/aaranxu/adidoks.git -cd adidoks -zola serve -``` - -Visit `http://127.0.0.1:1111/` in the browser. - -## Installation - -Just earlier we showed you how to run the theme directly. Now we start to -install the theme in an existing site step by step. - -### Step 1: Create a new zola site - -```bash -zola init mysite -``` - -### Step 2: Install AdiDoks - -Download this theme to your themes directory: - -```bash -cd mysite/themes -git clone https://github.com/aaranxu/adidoks.git -``` - -Or install as a submodule: - -```bash -cd mysite -git init # if your project is a git repository already, ignore this command -git submodule add https://github.com/aaranxu/adidoks.git themes/adidoks -``` - -### Step 3: Configuration - -Enable the theme in your `config.toml` in the site derectory: - -```toml -theme = "adidoks" -``` - -Or copy the `config.toml.example` from the theme directory to your project's -root directory: - -```bash -cp themes/adidoks/config.toml.example config.toml -``` - -### Step 4: Add new content - -You can copy the content from the theme directory to your project: - -```bash -cp -r themes/adidoks/content . -``` - -You can modify or add new posts in the `content/blog`, `content/docs` or other -content directories as needed. - -### Step 5: Run the project - -Just run `zola serve` in the root path of the project: - -```bash -zola serve -``` - -AdiDoks will start the Zola development web server accessible by default at -`http://127.0.0.1:1111`. Saved changes will live reload in the browser. diff --git a/content/docs/overview/design-overview.drawio b/content/docs/overview/design-overview.drawio new file mode 100644 index 0000000..afa9122 --- /dev/null +++ b/content/docs/overview/design-overview.drawio @@ -0,0 +1,118 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/content/docs/overview/design-overview.drawio.png b/content/docs/overview/design-overview.drawio.png new file mode 100644 index 0000000..11f3c23 Binary files /dev/null and b/content/docs/overview/design-overview.drawio.png differ diff --git a/content/docs/overview/flake_controller_new.epgz b/content/docs/overview/flake_controller_new.epgz new file mode 100644 index 0000000..f15a01a Binary files /dev/null and b/content/docs/overview/flake_controller_new.epgz differ diff --git a/content/docs/overview/flake_controller_new.png b/content/docs/overview/flake_controller_new.png new file mode 100644 index 0000000..8c57959 Binary files /dev/null and b/content/docs/overview/flake_controller_new.png differ diff --git a/content/docs/overview/index.md b/content/docs/overview/index.md new file mode 100644 index 0000000..3de2cab --- /dev/null +++ b/content/docs/overview/index.md @@ -0,0 +1,274 @@ ++++ +title = "Overview" +description = "Overview of cLAN's architecture, components and security" +date = 2021-05-01T18:10:00+00:00 +updated = 2021-07-13T18:10:00+00:00 +draft = false +weight = 410 +sort_by = "weight" +template = "docs/page.html" + +[extra] +lead = "Overview of cLAN's architecture, components and security" +toc = true +top = false ++++ + + +# cLAN + +cLAN envisions a new model for a decentralized network, designed to provide families, smaller groups, and small businesses a platform that's private, secure, and user-friendly. The system transcends the conventional reliance on centralized services, allowing for direct, end-to-end encrypted communication among users. Rooted in open-source software, cLAN ensures no vendor lock-in, and introduces robust features including remote management, backup functionality, user-friendly app store, and fleet management for small businesses. + +## Architecture Overview + +### Decentralized Network Model + +cLAN incorporates a decentralized network model to tackle the challenges posed by restrictive firewalls, NAT, and the scarcity of ipv4 address space. By leveraging end-to-end encryption, the model ensures all peers within the network are fully connected, allowing services and communication to occur directly. +This is achieved by the user of an decentralized virtual private network (VPN). A decentralized VPN is a system that uses multiple servers spread across different locations to create a secure, private network within an organization, enabling secure communication and data transfer without relying on a central server. The VPN serves as an added layer of security, shielding internal services from exposure to the open internet. + +This network model uses a decentralized method, similar to a phonebook, that translates website names into addresses that computers understand (i.e. using mDNS), which helps improve how users interact with the network. Looking forward, for businesses, the model plans to include rules that decide who can access which parts of the network, depending on their job role. + + + + +### NixOS as the Operating System + +* Motivation: Maintaining and configuring a decentralized system like cLAN with heterogeneous services on heterogeneous platforms is a challenging task. In professional setups this is usually solved by the use of configuration management. These systems require years of experience and are therefore not approchable by normal users. The solution so far to this problem is to provide instead appliances that are massivly locked in functionality or platforms they support. +* To overcome these limitations, we propose NixOS. +* NixOS is an operating system that uses a single declarative and consistent configuration to describe the whole system using its own programming language called Nix +* While Nix is not necessarily more user-friendly, we believe it's still the best fit to be configured through graphical user interface for the following reasons: The underlying data structures is simple enough to be generated from a user interface / assistant. Because it's declarative unlike other many configuration management systems, different modules can be composed and applied in any order. +* Especially in distributed setup where the adminstrator does not necessarily has physical access to the computers that require updates, NixOS provides atomic updates and rollbacks in case an update fail. We like to extend these capabilities with automatic rollbacks to make it easier to recover from a misconfiguration +* A user can join one or multiple networks. +* We use virtual machines (or containers) to isolate these networks. +* A virtual machine is a software-based imitation of a physical computer. It runs its own operating system, independent of the host machine's, allowing multiple virtual mahcines with varied configurations to operate simultaneously on one physical device. Virtual machines are often used for software testing, running outdated applications, and isolating potential security threats. +* Applications inside of virtual machines for users are preconfigured for services offered by the network + +The Nix configuration language allows the complete configurability and modifiability of any system it is applied to, regardless of complexity and size. It is used as the basis for NixOS to create a completely reproducible operating system, where the configuration of software services running on those machines is easily shared by using small, human-readable small code snippets called "NixOS Configurations". When using Nix and NixOS, software appears out of thin air, correctly configured the way you intended, each and every time. + +Nixpkgs is a collection of recipes, also referred to as "derivations", which allow the building, sharing and reproduction of an incredibly large set of computer software. These programs are compiled from source, which means they can be modified or sovereignly maintained. These build instructions are written in the Nix programming language. + +Nixpkgs also defines "modules" which permit the sharing of knowledge and implementation on how to run this software correctly. The past 50 years of operating system development and best practices has been encoded in Nixpkgs by legions of contributors. Sharing of esoteric system administration knowledge, previously inaccessible and fragmented across industry experts, has been made easy due to this work. + +From the perspective of the user, software and systems that once required years of experience to provision, can now be boiled down to a single, short Nix expression; a single line of code in most cases. + + +### Self-hosted backup and restore + +cLAN enables users to easily self-host and backup their data, since one of the perils of self-hosting is data loss. Users can build pre-configured servers from the interface where they also would be notified about devices not being backed up and view information about the storage device, such as available storage and state of arrays. + +It is possible for users to back up devices in their global network, regardless of how they are connected. Services installed provided by cLAN also need to be aware of the backup process i.e. some applications, such as databases, have custom backup and restore procedures that needs to be integrated in the backup procedure. + + + +## Components + + +Design +(figure 1) + +### Base-OS + +Initially, we will utilize NixOS as the foundational operating system for hosting network-specific virtual machines. Presently, the installation process of NixOS involves advanced technical knowledge, including a degree of proficiency in its unique programming language. However, our solution cLAN aims to simplify this process, enabling even non-technical individuals to successfully install the system. + +Several approaches can be considered to simplify the Base OS installation process: + +* Quick-to-implement solutions: + * Develop an installer that establishes a connection to a Virtual Private Network (VPN). This would enable a more proficient user or administrator to provide assistance or even conduct the installation process on behalf of the user. + * Design an installer capable of autonomously installing the operating system when initiated, for instance, via PXE (Preboot eXecution Environment) or USB. + +* More effort-intensive approach: Enhance the existing graphical installer to minimize the degree of technical knowledge (such as understanding of Nix) required by the user. + +#### Flake configuration manager + + +Our aim is to empower users to create a template for a virtual machine, essentially allowing them to define a flake.nix from an assortment of templates we offer as high-level NixOS modules through a graphical user-interface. The user-defined flake will contain several essential elements: + +Documentation: We will provide detailed guides on how to join and communicate within the network, as well as an overview of what the network has to offer. These guides will help users navigate the network and utilize its features to their fullest potential. + +Network joining configuration: To facilitate seamless connectivity, the flake will include configurations for Virtual Private Network (VPN), Domain Name System (DNS), and possibly bootstrap hosts. These configurations will ensure that users can easily join the network and maintain a stable connection. + +A default nixos configuration: Upon spawning a virtual machine, a default NixOS configuration will be included, preloaded with various apps. This feature enables users to kickstart their virtual machine experience with ready-to-use applications, eliminating the need for manual installation and configuration. + +Users will be able to establish their own networks and incorporate various features into it, such as a Git server, a shared Nextcloud instance, or automatic directory synchronization via Syncthing (see also 'Market Place' section below). + +Ideally, we envision this functionality in the form of a web application, an Android app, and possibly a terminal-based application for power users. These platforms will cater to different user preferences, promoting a more inclusive and user-friendly experience. + +an example flake.nix for a virtual machine network: + +```nix +{ + inputs.cLAN.url = "git+https://git.cLAN.com/cLAN"; + + outputs = { self, cLAN, ... }: + { + nixosModules = { + default = inputs.cLAN.nixosSystem { + imports = [ + cLAN.nixosModules.default + ]; + cLAN = { + adminMode = "local"; + networkLayer= "yggdrasil"; + applications = { + syncthing = { + enable = true; + sharedFolders = [ "/shared/docs" ]; + }; + mumbleClient.server = "mumble.cLAN"; + }; + }; + }; + }; + }; +} +``` + +To build the final VM, +This modules would be build by the VM controller into a system with the following flake.nix + +```nix +{ + inputs.myNetworkFlake = "git+https://somurl-where-I-can-get-flake.nix-from-above"; + + outputs = inputs: + { + nixosConfigurations.me = inputs.myNetworkFlake.inputs.nixpkgs.lib.nixosSystem { + imports = [ + inputs.myNetworkFlake.nixosModules.default + ./local-overrides.nix + ]; + } + } +} +``` + + + +the upper flake.nix can also be split into a boilerplate flake.nix and a json, which can be generated by a graphical interface. + +```nix +{ + inputs.cLAN.url = "git+https://git.cLAN.com/cLAN"; + + outputs = { self, cLAN, ... }: + { + nixosModules = cLAN.lib.generateNixosModules (builtins.fromJSON (import ./configs.json)); + }; +} +``` + +configs.json + +```json +{ + "default": { + "system": "x86_64-linux", + "adminMode": "local", + "networkLayer": "yggdrasil", + "applications": { + "syncthing": { + "enable": true, + "sharedFolders": [ "/shared/docs" ] + }, + "mumbleClient": { + "server": "mumble.cLAN" + } + } + } +} +``` + +A crude example of how this interface would look like +VM Manager New Network + + +### VM Manager + +The Base OS runs the VM Manager for monitoring and managing installed virtual machines. The VM Manager is a graphical interface that allows for various settings adjustments, such as enabling automatic updates, and the addition of new virtual machines. + +Virtual machines are tight to a specific VPN of a particular group, and their configurations are obtained from a remotely accessible flake. A flake is a collection of Nix code that comprehensively outlines the virtual machine's configuration. Virtual machines can be built and updated based on this flake. Networks can advertise their flakes via a Uniform Resource Identifier (URI) such as `nix://https-github.com/someorg/somerepo`, `nix://ipfs-$someIpfsHash`, or `nix://ygg-$someYggAddr`. These URIs can be automatically opened in the virtual manager graphical interface on a user's system when clicked, making the process of joining a network straightforward and efficient. + +If a user intends to join only a single network and their hardware capabilities are limited, an alternative to consider would be to forego the use of a virtual machine. Instead, the network configuration could be integrated directly into the Base-OS to optimize performance and enhance the user experience. + +Proxmox + +The interface to the VM-manager for network admins is very similiar to the proxmox interface used for managing multiple VM nodes. Showing a list of networks and corresponding VMs on the left with a detail view and monitoring/log stats in the middle. Information and Interaction with the target system is provided by the Controller described in the next section. + +### Virtual machine controller + +Controller +(figure 2) + +The Virtual Machine (VM) Manager operates on the Base OS, while the VM Controller functions within the virtual machine itself. The latter's role is to regulate the operating system within the VM, and can be managed by either the network administrator or the local user in control of the Base OS. Here are the different modes of control: + +* Remote Control: The network administrator can remotely access the machine using SSH. There's also a user-friendly interface for adjusting configuration settings, viewing computer statistics, or initiating a rebuild. +* Local Control: The network administrator sets up a flake which outlines the default services, like VPN and default applications. The local administrator, with root access, can then deploy their services, such as nginx, nextcloud etc., which are integrated with the defaults provided by the flake. +* Shared Control: Both the network and local administrators have complete access. While the local user can modify options defined by the flake.nix, either administrator can revoke these changes. + +In order to appeal to a wider audience beyond those already familiar with Nix/NixOS, we're suggesting the development of an easy-to-understand graphical interface. This interface will simplify the use of NixOS modules, provide vital monitoring and debugging information, and enable users to manage their individual virtual machines and NixOS installations more effectively. + +### Market place + +* There is some kind of store/market place where people can publish their flakes/networks +* Their source code will reside in their own repo, we might want some mirror (ipfs) in case their infrastructure goes down +* Donation/subscription fees for maintaining and creating flakes + + +### Private network + +* Adding a VPN should be the default for every flake.nix created by the wizard so people can easily communicate with each other and not care about extensive firewalling/ACLS/port forwarding etc. We can support different technologies like wireguard, tinc, yggdrasil, zerotier etc. Different higher level modules have to be created for that. + +### Integration into baseOS window manager + +* We want an integration with the i3/sway window manager where every workspace is it's own VM. At a later point we also want integration for a more common stacking WM (like Gnome). + +## Security + +The flake.nix describes a system which runs inside a virtual machine. It is evaluated on the system which then builds a virtual machine out of it via Nix. This way there is no interaction with the root operating system, except through the nix-daemon. +At a later point we can also build containers with the same system and have shared memory, gpu access and generally less overhead. Although additional safety measures have to be implemented for that. + +In this section we discuss security threats and how we design the system to mitigate those. + +### Threat-model and mitigations + +Our threat model is based on the potential risks from various adversaries, each of which are outlined below: + +* Malicious flakes/administrators: This includes individuals or entities with administrative privileges who intentionally act against the interests of the network users. They could manipulate configurations, grant unauthorized access, or misuse sensitive information. +Our safeguards will include virtual machine isolation to mitigate the damage an malicious actor can do to the target system. Malicious admins/flakes can only affect the virtual machine but not the Base OS or other virtual machines from other networks. Since the configuration is based on Nix, more experienced users can review it prior to building. This makes the system more auditable compared to a binary distribution, where only ready built packages are downloaded. + +* Malicious members in the network: These are network participants who may attempt to disrupt services, steal sensitive data, or exploit vulnerabilities. To counter this, we will implement methods for administrators to block/remove malicious actors from the network. As a long-term goal, business-oriented setups will include access control measures to regulate network access based on user roles. + +* Attackers from outside the network: These are external entities trying to infiltrate the network to gain unauthorized access or disrupt the network's operations. These are locked outside access to the system by the VPN technology we use. Since there is no way for outside attackers to even reach a virtual machine, they are considered safe for all intents and purposes from outside attackers. + * For attempts at lateral movement (i.e., the process of progressing through a network, system by system, in search of valuable data or to cause disruption), we will provide a default configuration for software we ship which we consider safe or hardened, to make it more difficult for an attacker to gain access to multiple systems. + +* Mis-configuration: This refers to inadvertent errors in the setup or configuration of the network that can inadvertently expose it to risks. +To address this, we only offer a limited set of options in our high-level modules, which either restrict or issue warnings for configurations deemed to be unsafe. +For instance, services are exposed exclusively to the internal network and not to the wider internet, thereby offering an extra layer of security. + +TODO: Threats that are out-of-scope + +### Trusted compute base + +The Trusted Compute Base (TCB) refers to the core set of security-critical elements in a computing system, such as the operating system kernel, hardware, and certain crucial applications. The integrity and reliability of the TCB are vital to the security of the whole system. + +In our case, the TCB encompasses the following key components: + +* The underlying VPN: This crucial part of our TCB provides a secure communication channel between different peers within the network. By encrypting all data that passes through it, the VPN ensures confidentiality and integrity of communications, thus safeguarding against eavesdropping or data tampering attempts. + +* The Hypervisor: Acting as the foundation for our virtual machines, the hypervisor manages and separates different networks, isolating them from one another. This prevents any potential cross-contamination or attacks between virtual machines, preserving the integrity and security of each separate network. + +* Nix Sandbox Isolation: This provides a safe way to build virtual machines, binaries, etc. in an isolated environment from the operating system. With this we can utilize the native speed of the Base OS for building the OS that runs inside the virtual machines. diff --git a/content/docs/overview/proxmox.png b/content/docs/overview/proxmox.png new file mode 100644 index 0000000..de6bcaa Binary files /dev/null and b/content/docs/overview/proxmox.png differ diff --git a/content/docs/overview/vm-controller.drawio b/content/docs/overview/vm-controller.drawio new file mode 100644 index 0000000..86615d4 --- /dev/null +++ b/content/docs/overview/vm-controller.drawio @@ -0,0 +1,82 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/content/docs/overview/vm-controller.drawio.png b/content/docs/overview/vm-controller.drawio.png new file mode 100644 index 0000000..06ba97a Binary files /dev/null and b/content/docs/overview/vm-controller.drawio.png differ