-
Notifications
You must be signed in to change notification settings - Fork 18
/
StratisSoftwareDesign.lyx
5911 lines (4667 loc) · 136 KB
/
StratisSoftwareDesign.lyx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#LyX 2.3 created this file. For more info see http://www.lyx.org/
\lyxformat 544
\begin_document
\begin_header
\save_transient_properties false
\origin unavailable
\textclass article
\begin_preamble
\end_preamble
\use_default_options true
\begin_modules
logicalmkup
\end_modules
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman "default" "default"
\font_sans "default" "default"
\font_typewriter "default" "default"
\font_math "auto" "auto"
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100 100
\font_tt_scale 100 100
\use_microtype false
\use_dash_ligatures false
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref false
\papersize default
\use_geometry false
\use_package amsmath 1
\use_package amssymb 1
\use_package cancel 1
\use_package esint 1
\use_package mathdots 1
\use_package mathtools 1
\use_package mhchem 1
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\justification true
\use_refstyle 1
\use_minted 0
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 1.5in
\topmargin 1in
\rightmargin 1.5in
\bottommargin 1in
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\is_math_indent 0
\math_numbering_side default
\quotes_style english
\dynamic_quotes 0
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header
\begin_body
\begin_layout Title
Stratis Software Design
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0
International License.
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Note Note
status collapsed
\begin_layout Plain Layout
Before saving this file preparatory to a commit, make sure that all insets
are closed.
If you are able to read this note, you haven't performed this essential
step.
\end_layout
\end_inset
\end_layout
\begin_layout Section*
About this Document
\end_layout
\begin_layout Standard
This document can be found
\begin_inset CommandInset href
LatexCommand href
name "in the stratis-docs repo"
target "https://github.com/stratis-storage/stratis-docs/blob/master/docs/design/StratisSoftwareDesign.lyx"
literal "false"
\end_inset
, and is written using \SpecialChar LyX
.
\end_layout
\begin_layout Section*
Summary
\end_layout
\begin_layout Standard
Stratis is an easily configured, tightly integrated solution for storage
that works within the existing Linux storage management stack.
To achieve this, Stratis prioritizes a straightforward command-line experience,
a rich API, and a fully automated, externally-opaque approach to storage
management.
It builds upon elements of the existing storage stack as much as possible.
\end_layout
\begin_layout Part
Background
\end_layout
\begin_layout Section
Problem Statement
\end_layout
\begin_layout Standard
Linux has gained many storage-related features over the years, but each
of these features has required the user to manage the configuration of
these features in a layered, additive manner.
Genuinely new and useful features such as thin provisioning, RAID, and
multipath are dependent on the user correctly configuring many different
layers via different tools to achieve a complete result.
Furthermore, since each layer's configuration tool only has a command-line
interface (CLI), higher-level management tools must each construct input
and parse the human-oriented output for each of these layers' CLIs.
This causes a waste of effort and opportunity for bugs, as each higher-level
tool builds its own internal API for the feature on top of the lower level
tool's CLI.
\end_layout
\begin_layout Subsection
Goal: Bring advanced features to users in a simpler form
\end_layout
\begin_layout Standard
Linux storage features are modular and stackable.
This promotes flexibility and allows independent development efforts, but
leads to a huge number of possible configurations.
This requires the user to manage the stack because there's not enough commonali
ty to enable effective automation.
\end_layout
\begin_layout Standard
But really, there
\emph on
is
\emph default
a single configuration that can work for most use cases.
By assuming a fixed layering of storage features (some perhaps optional),
we enable software to effectively manage these on behalf of the user.
\end_layout
\begin_layout Standard
Automated management then leads to less administrative burden placed on
the user.
The user still specifies resources, desired features, and results – what
hardware resources to use, what features to enable, how storage should
be logically presented – using a smaller number of concepts with well-defined
relations.
Software manages the rest, and handles most runtime issues without user
involvement.
\end_layout
\begin_layout Subsection
Proposal: Implement a hybrid Volume Managing Filesystem
\end_layout
\begin_layout Standard
In the past ten years,
\emph on
volume-managing filesystems
\emph default
(VMFs) such as ZFS and Btrfs have come into vogue and gained users, after
being previously available only on other UNIX-based operating systems.
These incorporate what would be handled by multiple tools under traditional
Linux into a single tool.
Redundancy, thin provisioning, volume management, and filesystems become
features within a single comprehensive, consistent configuration system.
Where a traditional Linux storage stack exposes the layers of block devices
to the user to manage, VMFs hide everything in a
\emph on
pool
\emph default
.
The user puts raw storage in the pool, the VMF manages the storage in the
pool, providing the features the user wants, and allows the user to create
filesystems from the pool without being concerned with the details.
\end_layout
\begin_layout Standard
Unfortunately, existing VMFs aren't easily used on enterprise Linux distribution
s like RHEL.
ZFS isn't an option RHEL can embrace due to licensing, Ubuntu notwithstanding.
Btrfs has no licensing issues, but maintaining up-to-date support for it
in enterprise kernels proved difficult.
\end_layout
\begin_layout Standard
We can see from the many developer-years of effort that have gone into these
two projects that writing a VMF is a tremendous, time-consuming undertaking.
We also can hear our users demanding their features and ease of use.
\end_layout
\begin_layout Standard
Rather than writing a new VMF from scratch, Stratis proposes to satisfy
VMF-like requirements by managing existing technologies on behalf of the
user, so that users can manage their storage using high-level concepts
like
\begin_inset Quotes eld
\end_inset
pool
\begin_inset Quotes erd
\end_inset
and
\begin_inset Quotes eld
\end_inset
filesystem
\begin_inset Quotes erd
\end_inset
, and remain unconcerned with the more complex details under the covers.
\end_layout
\begin_layout Standard
This is also a chance to learn from the benefits and shortcomings of existing
solutions.
We should not just copy ZFS.
ZFS is now fifteen years old and the storage landscape has changed since
its design.
We seek to satisfy the same needs that ZFS does, but also integrate more
tightly into today's increasingly automated storage management solutions
that span the data center as well as the local machine.
This is made possible by a hybrid, userspace-based approach.
\end_layout
\begin_layout Subsection
Requirements
\end_layout
\begin_layout Enumerate
\emph on
Make features easier to use in combination with each other
\emph default
: thin provisioning, snapshots, multipath, encryption, hardware reconfiguration,
monitoring, and a caching tier
\end_layout
\begin_layout Enumerate
Simple and comprehensive command-line interface
\end_layout
\begin_deeper
\begin_layout Enumerate
Simple
\end_layout
\begin_deeper
\begin_layout Enumerate
Single way to do things
\end_layout
\begin_layout Enumerate
Do not expose internal implementation details.
Gives Stratis more implementation freedom, and of little value since internals
are too complex to make manual user repairs practical
\end_layout
\begin_layout Enumerate
User typically will not use on a daily basis
\end_layout
\begin_deeper
\begin_layout Enumerate
Consistent commands that a user can guess at, and probably be right
\end_layout
\begin_layout Enumerate
Require explicitness from the user for potentially data-losing operations,
such as giving a
\begin_inset Quotes eld
\end_inset
–force
\begin_inset Quotes erd
\end_inset
option.
\end_layout
\end_deeper
\end_deeper
\begin_layout Enumerate
Comprehensive
\end_layout
\begin_deeper
\begin_layout Enumerate
User must master only one tool
\end_layout
\begin_layout Enumerate
Helps user learn: if task not possible through tool, it must not be worth
doing (or a good idea)
\end_layout
\end_deeper
\end_deeper
\begin_layout Enumerate
Programmatic language-neutral API for higher-level management tool integration
\end_layout
\begin_deeper
\begin_layout Enumerate
A clear next step for users after hitting the limitations of scripting the
CLI
\end_layout
\begin_layout Enumerate
Encourages tight integration and use of all features by higher-level tools
\end_layout
\end_deeper
\begin_layout Enumerate
Event-driven monitoring and alerts
\end_layout
\begin_deeper
\begin_layout Enumerate
Monitoring and alert messages expressed in terms of Stratis user-visible
simple concepts, not implementation details
\end_layout
\begin_layout Enumerate
Low CPU/memory overhead to monitoring
\end_layout
\begin_layout Enumerate
Only alert when action really is needed
\end_layout
\begin_layout Enumerate
Fail gracefully if alerts are unheeded
\end_layout
\end_deeper
\begin_layout Enumerate
Eliminate manual resizing of filesystems
\end_layout
\begin_deeper
\begin_layout Enumerate
Numerous problem reports throughout the years indicate that resizing filesystems
is an area where users feel unease, due to potential data loss if a mistake
is made.
No real reason to require the user do this any more.
\end_layout
\begin_layout Enumerate
Simpler for DevOps
\end_layout
\begin_layout Enumerate
Makes storage
\begin_inset Quotes eld
\end_inset
demand-allocated
\begin_inset Quotes erd
\end_inset
, similar to virtual memory.
Current technology allows us to manage a filesystem's actual usage up (growfs)
or down (thin provisioning).
\end_layout
\end_deeper
\begin_layout Enumerate
Initrd-capable
\end_layout
\begin_deeper
\begin_layout Enumerate
Allows root fs, all other filesystems except /boot to use Stratis.
Needed for ease of use
\end_layout
\begin_layout Enumerate
Limited environment – alternate IPC mechanism that works in the initrd is
available
\end_layout
\end_deeper
\begin_layout Enumerate
Adaptable to emerging storage technologies
\end_layout
\begin_deeper
\begin_layout Enumerate
Persistent memory
\end_layout
\begin_deeper
\begin_layout Enumerate
Block-appearing pmem can be used by Stratis
\end_layout
\end_deeper
\end_deeper
\begin_layout Enumerate
Implementable in 1-2 years
\end_layout
\begin_deeper
\begin_layout Enumerate
We're already behind, waiting another 10 years isn't an option
\end_layout
\end_deeper
\begin_layout Part
Solution Overview
\end_layout
\begin_layout Section
Introduction
\end_layout
\begin_layout Standard
Stratis is a local storage solution that lets multiple logical filesystems
share a pool of storage that is allocated from one or more block devices.
Instead of an entirely in-kernel approach like ZFS or Btrfs, Stratis uses
a hybrid user/kernel approach that builds upon existing block capabilities
like device-mapper, existing filesystem capabilities like XFS, and a user
space daemon for monitoring and control.
\end_layout
\begin_layout Standard
The goal of Stratis is to provide the conceptual simplicity of volume-managing
filesystems, and surpass them in areas such as monitoring and notification,
automatic reconfiguration, and integration with higher-level storage management
frameworks.
\end_layout
\begin_layout Section
Stratis and the Linux storage stack
\end_layout
\begin_layout Standard
Stratis simplifies many aspects of local storage provisioning and configuration.
This, along with its API, would let projects dependent on configuring local
storage do so much more easily.
\end_layout
\begin_layout Standard
For example, installing the OS to a Stratis pool using Anaconda.
After selecting the disks to use for the pool, the first benefit would
be the complex flow around sizing of filesystems could be omitted.
Second, since Stratis has an API, Anaconda could use it, instead of needing
work in Blivet to build an API on top of command line tools.
\end_layout
\begin_layout Standard
Other management tools like Cockpit, virtualization products like RHEV,
or container products like Atomic would find it much simpler and less error-pro
ne to use storage and snapshots with Stratis, for the same two reasons:
don't need to worry about per-filesystem sizing (only that the pool has
enough
\begin_inset Quotes eld
\end_inset
backing store
\begin_inset Quotes erd
\end_inset
); and the API, which allows better tool-to-tool integration than using
CLI programmatically.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename stratis-interactions.svg
scale 80
\end_inset
\begin_inset Caption Standard
\begin_layout Plain Layout
Future Stratis Position in the Linux Storage Management Stack
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Section
Conceptual Model
\end_layout
\begin_layout Subsection
Blockdevs, pools, and filesystems
\end_layout
\begin_layout Standard
Stratis’s conceptual model consists of
\emph on
blockdevs
\emph default
,
\emph on
pools
\emph default
, and
\emph on
filesystems
\emph default
.
A pool is created from one or more blockdevs (block devices), and then
filesystems are created from the pool.
Filesystems are mountable hierarchical collections of files that allocate
backing storage from the pool as it is needed.
The key difference between a Stratis filesystem and a conventional Unix
filesystem is that Stratis filesystem sizing and maintenance are not managed
by the user, but by Stratis.
\end_layout
\begin_layout Subsection
Attributes and features of a pool
\end_layout
\begin_layout Standard
A pool is created with an initial set of one or more blockdevs.
Blockdevs may also be added after the pool is created.
The pool's primary collection of blockdevs is called the
\emph on
data tier
\emph default
.
\end_layout
\begin_layout Standard
A pool also optionally has a
\emph on
cache tier
\emph default
that uses a separate collection of faster blockdevs to improve performance
instead of increasing the pool's capacity.
\end_layout
\begin_layout Standard
Since a single system may have multiple pools, each pool has a name, as
does each filesystem within a pool.
These are both settable by the user.
Blockdevs, pools, and filesystems also have UUIDs, which are not settable
by the user.
\end_layout
\begin_layout Standard
Stratis supports large numbers of blockdevs and up to
\begin_inset Formula $2^{24}$
\end_inset
filesystems per pool.
However, practical limits on these values may compel users to restrict
themselves to smaller numbers of blockdevs and filesystems.
\end_layout
\begin_layout Standard
A new filesystem is either a new empty filesystem or a snapshot of an existing
filesystem within the pool.
Stratis currently does not distinguish between snapshots and filesystems.
\end_layout
\begin_layout Section
Scalability and Performance Considerations
\end_layout
\begin_layout Standard
Stratis doesn't optimize performance within its data tier, instead focusing
there on flexibility and integrity.
Improved performance is the job of caching tier, or perhaps building the
pool using blockdevs with higher IOPs, such as SSDs.
\end_layout
\begin_layout Part
\begin_inset CommandInset label
LatexCommand label
name "part:Implementation"
\end_inset
Implementation
\end_layout
\begin_layout Section
Software Components
\end_layout
\begin_layout Standard
Stratis consists of a command-line tool,
\emph on
stratis
\emph default
, and a service,
\emph on
stratisd
\emph default
.
\end_layout
\begin_layout Standard
stratis implements the command-line interface, and converts commands into
D-Bus API calls to stratisd.
\end_layout
\begin_layout Standard
stratisd implements the D-Bus interface, and manages and monitors Stratis
internal pool blockdevs, as described below.
It is started by the system and continues to run as long as Stratis pools
or blockdevs are present in the system.
\end_layout
\begin_layout Standard
stratisd includes a simulator engine.
The simulator engine is purely computational and does not affect the environmen
t, although it does communicate over the D-Bus.
\end_layout
\begin_layout Standard
Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:stratis"
plural "false"
caps "false"
noprefix "false"
\end_inset
shows the basic Stratis architecture.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename stratis.svg
scale 50
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption Standard
\begin_layout Plain Layout
Stratis Architecture
\end_layout
\end_inset
\begin_inset CommandInset label
LatexCommand label
name "fig:stratis"
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Section
User Experience
\end_layout
\begin_layout Standard
Stratis has a command-line tool that enables the administrator to create
a Stratis pool from one or more blockdevs, and then allocate filesystems
from the pool.
\end_layout
\begin_layout Standard
See reference implementation at
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
https://github.com/stratis-storage/stratis-cli
\end_layout
\end_inset
for the most up-to-date status of the CLI design.
\end_layout
\begin_layout Standard
This component is not required to be installed, in cases such as an appliance
where a higher-level application such as Cockpit or Ansible uses the D-Bus
API directly.
\end_layout
\begin_layout Subsection
Known shortcomings
\end_layout
\begin_layout Standard
Stratis' goal is to hide the complexity of its implementation from the user,
but by using a reuse/layering approach to its implementation, there will
be places where Stratis' implementation details will peek through.
This could cause user confusion, and also could threaten Stratis integrity
if the user makes changes.
\end_layout
\begin_layout Itemize
For Stratis filesystems, 'df' will report the current used and free sizes
as seen and reported by XFS.
This is not useful information, because the filesystem's actual storage
usage will be less due to thin provisioning, and also because Stratis will
automatically grow the filesystem if it nears XFS's currently sized capacity.
\end_layout
\begin_layout Itemize
Users should not try to reformat or reconfigure XFS filesystems that are
managed by Stratis.
Stratis has no way to enforce this or warn the user to avoid this, other
than in the documentation.
\end_layout
\begin_layout Itemize
Stratis will use many device-mapper devices, which will show up in `dmsetup`
listings and /proc/partitions.
Similarly, `lsblk` output on a Stratis system will reflect Stratis' internal
workings and layers.
\end_layout
\begin_layout Itemize
Stratis requires a userspace daemon, which must remain running at all times
for proper monitoring and pool maintenance.
\end_layout
\begin_layout Section
D-Bus Programmatic API
\end_layout
\begin_layout Standard
The Stratis service process exposes a D-Bus interface, for other programs
to integrate support for Stratis.
This is considered the primary Stratis interface.
The command-line tool uses the D-Bus API.
\end_layout
\begin_layout Subsection
Overview
\end_layout
\begin_layout Standard
The D-Bus API is part of stratisd.
It is a thin layer that receives messages on the D-Bus, processes them,
transmits them to the Stratis engine, receives the results from the engine,
and returns the result to the invoker of the API.
When processing method calls, its responsibilities are confined to:
\end_layout
\begin_layout Itemize
Receiving arguments and verifying that they conform to the signature of
the invoked method.
\end_layout
\begin_layout Itemize
Transforming method arguments received on the D-Bus to arguments of the
appropriate type to be passed to engine methods.
\end_layout
\begin_layout Itemize
Converting tuple arguments used to represent non-mandatory arguments to
values which inhabit the Rust Option type.
\end_layout
\begin_layout Itemize
Invoking the appropriate engine methods and capturing their return values.
\end_layout
\begin_layout Itemize
Marshalling the appropriate return values to place on the D-Bus along with
the return code and message.
\end_layout
\begin_layout Itemize
Adding or removing objects from the D-Bus tree.
\end_layout
\begin_layout Standard
The D-Bus API is implemented using the dbus-rs library
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
https://github.com/diwic/dbus-rs
\end_layout
\end_inset
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
The Stratisd D-Bus API Reference Manual contains a description of the API.
\end_layout
\begin_layout Subsection
D-Bus Access Control
\end_layout
\begin_layout Subsubsection
Security Policy
\end_layout
\begin_layout Standard
Most stratisd D-Bus methods require root permissions.
However, listing operations do not; these can be done by an unprivileged
user.
The default permissions are specified in the policy file, stratisd.conf,
included in the stratisd distribution.
These defaults permit all actions by root users but restrict unprivileged
users to read-only actions.
Systems administrators can adjust permissions by editing the stratisd D-Bus
policy files.
\end_layout
\begin_layout Subsection
Querying stratisd state via D-Bus
\end_layout
\begin_layout Standard
stratisd exposes a reporting interface that allows users to query the state
of stratisd's internal data structures for debugging and error reporting.
The D-Bus query returns a JSON string that can be parsed to detect state
programmatically; however, the report interface is unstable, and consequently
the names and schemas of provided reports do not follow the semantic versioning
rules to which the rest of stratisd's API conforms.
\end_layout
\begin_layout Section
JSON RPC IPC mechanism
\end_layout
\begin_layout Subsection
Overview
\end_layout
\begin_layout Standard
Due to restrictions in the initramfs where D-Bus is not currently present,
there is an alternate mechanism for IPC in the initramfs.
This IPC mechanism implements a JSON RPC framework passed over Unix sockets.
The motivation for using Unix sockets is that:
\end_layout
\begin_layout Enumerate
They are available in the initramfs as a form of IPC
\end_layout
\begin_layout Enumerate
They allow passing file descriptors from process to process in the same
network packet as the JSON
\end_layout
\begin_layout Standard
The JSON RPC IPC mechanism uses the exact same code for the stratisd storage
engine and is simply a thin layer that handles all of the network operations
and input parsing to provide arguments to the engine.
The initramfs IPC API is more limited than that of the D-Bus API and is
not versioned for backwards compatibility given that it is expected that
the corresponding CLI will be used to communicate with the minimal daemon.
\end_layout
\begin_layout Section
Internals
\end_layout
\begin_layout Standard
Stratis internals aim to be opaque to the user.
This allows its implementation maximum flexibility to do whatever it needs
in Stratis version 1, as well as to be extended in later versions without
violating any user-visible expectations.
\end_layout
\begin_layout Subsection
Data Tier Requirements
\end_layout
\begin_layout Standard
The data tier of Stratis must manage blockdevs on behalf of the user to
provide the following:
\end_layout
\begin_layout Enumerate
Managed filesystems that consume only as much space as the files they contain
\end_layout
\begin_layout Enumerate