1.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2+++ b/nas-t/api.org Sun Nov 05 22:46:15 2023 -0500
1.3@@ -0,0 +1,5 @@
1.4+#+TITLE: api
1.5+* Overview
1.6+* Protocols
1.7+* Filesystems
1.8+* Objects
2.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2+++ b/nas-t/install.org Sun Nov 05 22:46:15 2023 -0500
2.3@@ -0,0 +1,6 @@
2.4+#+TITLE: install
2.5+* Overview
2.6+#+begin_src sh
2.7+ make build
2.8+ # make install
2.9+#+end_src
3.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2+++ b/nas-t/notes.org Sun Nov 05 22:46:15 2023 -0500
3.3@@ -0,0 +1,235 @@
3.4+#+TITLE: notes
3.5+#+BIBLIOGRAPHY: refs.bib
3.6+* File Systems
3.7+** BTRFS
3.8+#+begin_quote
3.9+BTRFS is a Linux filesystem based on copy-on-write, allowing for
3.10+efficient snapshots and clones.
3.11+
3.12+It uses B-trees as its main on-disk data structure. The design goal is
3.13+to work well for many use cases and workloads. To this end, much
3.14+effort has been directed to maintaining even performance as the
3.15+filesystem ages, rather than trying to support a particular narrow
3.16+benchmark use-case.
3.17+
3.18+Linux filesystems are installed on smartphones as well as enterprise
3.19+servers. This entails challenges on many different fronts.
3.20+
3.21+- Scalability :: The filesystem must scale in many dimensions: disk
3.22+ space, memory, and CPUs.
3.23+
3.24+- Data integrity :: Losing data is not an option, and much effort is
3.25+ expended to safeguard the content. This includes checksums, metadata
3.26+ duplication, and RAID support built into the filesystem.
3.27+
3.28+- Disk diversity :: The system should work well with SSDs and hard
3.29+ disks. It is also expected to be able to use an array of different
3.30+ sized disks, which poses challenges to the RAID and striping
3.31+ mechanisms.
3.32+#+end_quote
3.33+-- [cite/t/f:@btrfs]
3.34+*** [2023-08-08 Tue] btrfs performance speculation ::
3.35+ - [[https://www.percona.com/blog/taking-a-look-at-btrfs-for-mysql/]]
3.36+ - zfs outperforms immensely, but potential misconfiguration on btrfs side (virt+cow
3.37+ still enabled?)
3.38+ - https://www.ctrl.blog/entry/btrfs-vs-ext4-performance.html
3.39+ - see the follow up comment on this post
3.40+ - https://www.reddit.com/r/archlinux/comments/o2gc42/is_the_performance_hit_of_btrfs_serious_is_it/
3.41+ #+begin_quote
3.42+ I’m the author of OP’s first link. I use BtrFS today. I often shift lots of
3.43+ de-duplicatable data around, and benefit greatly from file cloning. The data is actually
3.44+ the same data that caused the slow performance in the article. BtrFS and file cloning
3.45+ now performs this task quicker than a traditional file system. (Hm. It’s time for a
3.46+ follow-up article.)
3.47+
3.48+ In a laptop with one drive: it doesn’t matter too much unless you do work that benefit
3.49+ from file cloning or snapshots. This will likely require you to adjust your tooling and
3.50+ workflow. I’ve had to rewrite the software I use every day to make it take advantage of
3.51+ the capabilities of a more modern file system. You won’t benefit much from the data
3.52+ recovery and redundancy features unless you’ve got two storage drives in your laptop and
3.53+ can setup redundant data copies.
3.54+
3.55+ on similar hardware to mine?
3.56+
3.57+ It’s not a question about your hardware as much as how you use it. The bad performance I
3.58+ documented was related to lots and lots of simultaneous random reads and writes. This
3.59+ might not be representative of how you use your computer.
3.60+ #+end_quote
3.61+ - https://dl.acm.org/doi/fullHtml/10.1145/3386362
3.62+ - this is about distributed file systems (in this case Ceph) - they argue against
3.63+ basing DFS on ondisk-format filesystems (XFS ext4) - developed BlueStore as
3.64+ backend, which runs directly on raw storage hardware.
3.65+ - this is a good approach, but expensive (2 years in development) and risky
3.66+ - better approach is to take advantage of a powerful enough existing ondisk-FS
3.67+ format and pair it with supporting modules which abstract away the 'distributed'
3.68+ mechanics.
3.69+ - the strategy presented here is critical for enterprise-grade hardware where the
3.70+ ondisk filesystem becomes the bottleneck that you're looking to optimize
3.71+ - https://lore.kernel.org/lkml/cover.1676908729.git.dsterba@suse.com/
3.72+ - linux 6.3 patch by David Sterba [2023-02-20 Mon]
3.73+ - btrfs continues to show improvements in the linux kernel, ironing out the kinks
3.74+ - makes it hard to compare benchmarks tho :/
3.75+*** MacOS support
3.76+- see this WIP k-ext for macos: [[https://github.com/relalis/macos-btrfs][macos-btrfs]]
3.77+ - maybe we can help out with the VFS/mount support
3.78+*** on-disk format
3.79+- [[https://btrfs.readthedocs.io/en/latest/dev/On-disk-format.html][on-disk-format]]
3.80+- 'btrfs consists entirely of several trees. the trees use copy-on-write.'
3.81+- trees are stored in nodes which belong to a level in the b-tree structure.
3.82+- internal nodes (inodes) contain refs to other inodes on the /next/ level OR
3.83+ - to leaf nodes then the level reaches 0.
3.84+- leaf nodes contain various types depending on the tree.
3.85+- basic structures
3.86+ - 0:8 uint = objectid, each tree has its own set of object IDs
3.87+ - 8:1 uint = item type
3.88+ - 9:8 uint = offset, depends on type.
3.89+ - little-endian
3.90+ - fields are unsigned
3.91+ - *superblock*
3.92+ - primary superblock is located at 0x10000 (64KiB)
3.93+ - Mirror copies of the superblock are located at physical addresses 0x4000000 (64
3.94+ MiB) and 0x4000000000 (256GiB), if valid. copies are updated simultaneously.
3.95+ - during mount only the first super block at 0x10000 is read, error causes mount to
3.96+ fail.
3.97+ - BTRFS onls recognizes disks with a valid 0x10000 superblock.
3.98+ - *header*
3.99+ - stored at the start of every inode
3.100+ - data following it depends on whether it is an internal or leaf node.
3.101+ - *inode*
3.102+ - node header followed by a number of key pointers
3.103+ - 0:11 key
3.104+ - 11:8 uint = block number
3.105+ - 19:8 uint = generation
3.106+ - *lnode*
3.107+ - leaf nodes contain header followed by key pointers
3.108+ - 0:11 key
3.109+ - 11:4 uint = data offset relative to end of header(65)
3.110+ - 15:4 uint = data size
3.111+- objects
3.112+ - ROOT_TREE
3.113+ - holds ROOT_ITEMs, ROOT_REFs, and ROOT_BACKREFs for every tree other than itself.
3.114+ - used to find the other trees and to determine the subvol structure.
3.115+ - holds items for the 'root tree directory'. laddr is store in the superblock
3.116+ - objectIDs
3.117+ - free ids: BTRFS_FIRST_FREE_OBJECTID=256ULL:BTRFS_LAST_FREE_OBJECTID=-256ULL
3.118+ - otherwise used for internal use
3.119+*** send-stream format
3.120+- [[https://btrfs.readthedocs.io/en/latest/dev/dev-send-stream.html][send stream format]]
3.121+- Send stream format represents a linear sequence of commands describing actions to be
3.122+ performed on the target filesystem (receive side), created on the source filesystem
3.123+ (send side).
3.124+- The stream is currently used in two ways: to generate a stream representing a
3.125+ standalone subvolume (full mode) or a difference between two snapshots of the same
3.126+ subvolume (incremental mode).
3.127+- The stream can be generated using a set of other subvolumes to look for extent
3.128+ references that could lead to a more efficient stream by transferring only the
3.129+ references and not full data.
3.130+- The stream format is abstracted from on-disk structures (though it may share some
3.131+ BTRFS specifics), the stream instructions could be generated by other means than the
3.132+ send ioctl.
3.133+- it's a checksum+TLV
3.134+- header: u32len,u16cmd,u32crc32c
3.135+- data: type,length,raw data
3.136+- the v2 protocol supports the encoded commands
3.137+- the commands are kinda clunky - need to MKFIL/MKDIR then RENAM to create
3.138+*** [2023-08-09 Wed] ioctls
3.139+- magic#: 0x94
3.140+ - https://docs.kernel.org/userspace-api/ioctl/ioctl-number.html
3.141+ - Btrfs filesystem some lifted to vfs/generic
3.142+ - fs/btrfs/ioctl.h and linux/fs.h
3.143+** ZFS
3.144+-- [cite/t/f:@zfs]
3.145+
3.146+- core component of TrueNAS software
3.147+** TMPFS
3.148+-- [cite/t/f:@tmpfs]
3.149+- in-mem FS
3.150+** EXT4
3.151+-- [cite/t/f:@ext4]
3.152+** XFS
3.153+-- [cite/t/f:@xfs]
3.154+-- [cite/t/f:@xfs-scalability]
3.155+* Storage Mediums
3.156+** HDD
3.157+-- [cite/t/f:@hd-failure-ml]
3.158+** SSD
3.159+-- [cite/t/f:@smart-ssd-qp]
3.160+-- [cite/t/f:@ssd-perf-opt]
3.161+
3.162+** Flash
3.163+-- [cite/t/f:@flash-openssd-systems]
3.164+** NVMe
3.165+-- [cite/t/f:@nvme-ssd-ux]
3.166+-- [[https://nvmexpress.org/specifications/][specifications]]
3.167+*** ZNS
3.168+-- [cite/t/f:@zns-usenix]
3.169+#+begin_quote
3.170+Zoned Storage is an open source, standards-based initiative to enable data centers to
3.171+scale efficiently for the zettabyte storage capacity era. There are two technologies
3.172+behind Zoned Storage, Shingled Magnetic Recording (SMR) in ATA/SCSI HDDs and Zoned
3.173+Namespaces (ZNS) in NVMe SSDs.
3.174+#+end_quote
3.175+-- [[https://zonedstorage.io/][zonedstorage.io]]
3.176+-- $465 8tb 2.5"? [[https://www.serversupply.com/SSD/PCI-E/7.68TB/WESTERN%20DIGITAL/WUS4BB076D7P3E3_332270.htm][retail]]
3.177+** eMMC
3.178+-- [cite/t/f:@emmc-mobile-io]
3.179+* Linux
3.180+** syscalls
3.181+*** ioctl
3.182+- [[https://elixir.bootlin.com/linux/latest/source/Documentation/userspace-api/ioctl/ioctl-number.rst][ioctl-numbers]]
3.183+* Rust
3.184+** crates
3.185+*** nix
3.186+- [[https://crates.io/crates/nix][crates.io]]
3.187+*** memmap2
3.188+- [[https://crates.io/crates/memmap2][crates.io]]
3.189+*** zstd
3.190+- [[https://crates.io/crates/zstd][crates.io]]
3.191+*** rocksdb
3.192+- [[https://crates.io/crates/rocksdb][crates.io]]
3.193+*** tokio :tokio:
3.194+- [[https://crates.io/crates/tokio][crates.io]]
3.195+*** tracing :tokio:
3.196+- [[https://crates.io/crates/tracing][crates.io]]
3.197+**** tracing-subscriber
3.198+- [[https://crates.io/crates/tracing-subscriber][crates.io]]
3.199+*** axum :tokio:
3.200+- [[https://crates.io/crates/axum][crates.io]]
3.201+*** tower :tokio:
3.202+- [[https://crates.io/crates/tower][crates.io]]
3.203+*** uuid
3.204+- [[https://crates.io/crates/uuid][crates.io]]
3.205+** unstable
3.206+*** lazy_cell
3.207+- [[https://github.com/rust-lang/rust/issues/109736][tracking-issue]]
3.208+*** {BTreeMap,BTreeSet}::extract_if
3.209+- [[https://github.com/rust-lang/rust/issues/70530][tracking-issue]]
3.210+* Lisp
3.211+** ASDF
3.212+- [[https://gitlab.common-lisp.net/asdf/asdf][gitlab.common-lisp.net]]
3.213+- [[https://asdf.common-lisp.dev/][common-lisp.dev]]
3.214+- [[https://github.com/fare/asdf/blob/master/doc/best_practices.md][best-practices]]
3.215+- includes UIOP
3.216+** Reference Projects
3.217+*** StumpWM
3.218+- [[https://github.com/stumpwm/stumpwm][github]]
3.219+*** Nyxt
3.220+- [[https://github.com/atlas-engineer/nyxt][github]]
3.221+*** Kons-9
3.222+- [[https://github.com/kaveh808/kons-9][github]]
3.223+*** cl-torrents
3.224+- [[https://github.com/vindarel/cl-torrents][github]]
3.225+*** Mezzano
3.226+- [[https://github.com/froggey/Mezzano][github]]
3.227+*** yalo
3.228+- [[https://github.com/whily/yalo][github]]
3.229+*** cl-ledger
3.230+- [[https://github.com/ledger/cl-ledger][github]]
3.231+*** Lem
3.232+- [[https://github.com/lem-project/lem][github]]
3.233+*** kindista
3.234+- [[https://github.com/kindista/kindista][github]]
3.235+*** lisp-chat
3.236+- [[https://github.com/ryukinix/lisp-chat][github]]
3.237+* Refs
3.238+#+print_bibliography:
4.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2+++ b/nas-t/quickstart.org Sun Nov 05 22:46:15 2023 -0500
4.3@@ -0,0 +1,4 @@
4.4+#+TITLE: quickstart
4.5+* Install
4.6+* Configure the daemon
4.7+* Connect a client
5.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2+++ b/nas-t/readme.org Sun Nov 05 22:46:15 2023 -0500
5.3@@ -0,0 +1,15 @@
5.4+#+TITLE: index
5.5+#+DESCRIPTION: NAS-T Documentation
5.6+
5.7+Welcome to the documentation home of NAS-T. Choose one of the topics below to get
5.8+started.
5.9+
5.10+- [[file:quickstart.org][Quickstart]] :: get your private cloud now.
5.11+
5.12+- [[file:install.org][Install]] :: complete installation guide.
5.13+
5.14+- [[file:tutorial.org][Tutorial]] :: in-depth tutorial with detailed examples.
5.15+
5.16+- [[file:roadmap.org][Roadmap]] :: The NAS-T development roadmap.
5.17+
5.18+- [[file:api.org][API]] :: API Documentation for NAS-T hackers.
6.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2+++ b/nas-t/roadmap.org Sun Nov 05 22:46:15 2023 -0500
6.3@@ -0,0 +1,110 @@
6.4+#+TITLE: roadmap
6.5+* 0.1.0 [0/3] :current:
6.6+** TODO MVP [1/6]
6.7+:LOGBOOK:
6.8+- State "TODO" from [2023-08-01 Tue 19:14]
6.9+:END:
6.10+*** DONE acquire domain
6.11+:LOGBOOK:
6.12+- State "DONE" from [2023-08-01 Tue 19:16]
6.13+:END:
6.14+- [X] nas-t.net
6.15+*** DRAFT nas-t.net :web:rust:
6.16+:LOGBOOK:
6.17+- State "DRAFT" from "TODO" [2023-08-23 Wed 22:21]
6.18+- State "TODO" from [2023-08-01 Tue 19:14]
6.19+:END:
6.20+A basic landing page with the NAS-T mission, links, and contact info
6.21+is needed.
6.22+
6.23+The site should be a web-app and have basic client-side request
6.24+capabilities for submitting inquiries/comments.
6.25+**** TODO client [0/3] :client:
6.26+:LOGBOOK:
6.27+- State "TODO" from [2023-08-01 Tue 19:23]
6.28+:END:
6.29+SPA
6.30+***** TODO styles :style:
6.31+:LOGBOOK:
6.32+- State "TODO" from [2023-08-01 Tue 19:19]
6.33+:END:
6.34+Put together some color palettes and sass to make our web components
6.35+pretty. Design in modular fashion.
6.36+***** TODO components
6.37+:LOGBOOK:
6.38+- State "TODO" from [2023-08-01 Tue 19:22]
6.39+:END:
6.40+- [X] index
6.41+- [X] about
6.42+- [X] contact
6.43+ - [ ] >ty
6.44+- [X] page
6.45+- [X] app
6.46+- [ ] err
6.47+***** TODO hooks
6.48+:LOGBOOK:
6.49+- State "TODO" from [2023-08-01 Tue 19:22]
6.50+:END:
6.51+****** TODO mailme
6.52+:LOGBOOK:
6.53+- State "TODO" from [2023-08-01 Tue 19:30]
6.54+:END:
6.55+**** TODO server [0/2] :server:
6.56+:LOGBOOK:
6.57+- State "TODO" from [2023-08-01 Tue 19:22]
6.58+:END:
6.59+***** TODO mailme route
6.60+:LOGBOOK:
6.61+- State "TODO" from [2023-08-01 Tue 19:29]
6.62+:END:
6.63+- form submit
6.64+ - email
6.65+ - name
6.66+ - message
6.67+- return status
6.68+***** TODO errors
6.69+:LOGBOOK:
6.70+- State "TODO" from [2023-08-01 Tue 19:32]
6.71+:END:
6.72+- basic scaffolding
6.73+- [ ] impl IntoResponse
6.74+*** OUTLINE daemon :design:
6.75+:LOGBOOK:
6.76+- State "OUTLINE" from "TODO" [2023-08-23 Wed 22:21]
6.77+- State "TODO" from [2023-08-01 Tue 19:33]
6.78+:END:
6.79+*** OUTLINE protocol :design:
6.80+:LOGBOOK:
6.81+- State "OUTLINE" from "TODO" [2023-08-23 Wed 22:21]
6.82+- State "TODO" from [2023-08-01 Tue 19:34]
6.83+:END:
6.84+*** TODO nas-t CLI client :design:impl:
6.85+:LOGBOOK:
6.86+- State "TODO" from [2023-08-01 Tue 19:34]
6.87+:END:
6.88+*** TBD prototype
6.89+:LOGBOOK:
6.90+- State "TBD" from "TODO" [2023-08-23 Wed 22:22]
6.91+- State "TODO" from [2023-08-01 Tue 19:36]
6.92+:END:
6.93+- proof-of-concept on x86-64 GNU/Linux Intel CPU (zor)
6.94+- run on LAN with remote clients
6.95+- show capabilities and limitations
6.96+- perform basic benchmarks and discuss results
6.97+** TBD pitch [0/0]
6.98+- marketing/community approach
6.99+- define rhetoric
6.100+- optimized for variety of audiences
6.101+** TBD demo [0/0]
6.102+- assess hardware options
6.103+ - soc
6.104+ - must run GNU/Linux (for now..)
6.105+ - look locally, what can be re-purposed?
6.106+ - compare performance,heat,cost
6.107+ - storage
6.108+ - define required I/O speeds
6.109+ - define standard connector reqs based on soc
6.110+ - optimize linux kernel/dist
6.111+- infra/releng infra/deploy
6.112+- no accessories, ssh access only (or display port based on soc)
6.113+* 0.2.0 [0/1] :next:
7.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2+++ b/nas-t/tutorial.org Sun Nov 05 22:46:15 2023 -0500
7.3@@ -0,0 +1,14 @@
7.4+#+TITLE: tutorial
7.5+* Overview
7.6+** Introduction
7.7+** The Cloud
7.8+*** Services
7.9+**** Google
7.10+**** DropBox
7.11+**** Amazon
7.12+*** Protocols
7.13+**** HTTP
7.14+- gdrive,dropbox,s3
7.15+**** RSYNC
7.16+**** FTP
7.17+**** WebDAV
9.1--- a/style.org Sun Nov 05 21:44:43 2023 -0500
9.2+++ b/style.org Sun Nov 05 22:46:15 2023 -0500
9.3@@ -10,14 +10,35 @@
9.4
9.5 [fn:1] https://google.github.io/styleguide/
9.6
9.7+* General Programming
9.8+
9.9+- indent-offset = 2
9.10+- max-line-width = 80
9.11+- page-length ~ 32
9.12+- module-length ~ 512
9.13+- file-size ~ 1024
9.14+
9.15+- start every source-file with a header comment
9.16+- use outline headings to organize your program
9.17+- use ulang-comments as needed for referencing bugs, notes, etc.
9.18+- inline documentation should be declarative. your code explains your
9.19+ comments for you.
9.20+
9.21 * Common Lisp
9.22
9.23+- prefer symbol docs to comment docs
9.24+
9.25+** File templates
9.26 * Rust
9.27
9.28+- don't make =mod.rs= files
9.29+ - use the =foo.rs=, =foo/*= pattern instead
9.30+** File templates
9.31 * Emacs Lisp
9.32-
9.33+** File templates
9.34 * Org-mode
9.35-
9.36+** File templates
9.37 * Shell
9.38-
9.39+** File templates
9.40 * Python
9.41+** File templates
