From 31696a280873d0e2ff55c99a88652b330d0ddc60 Mon Sep 17 00:00:00 2001 From: Yashodhan Joshi Date: Wed, 22 Dec 2021 18:04:19 +0530 Subject: [PATCH] Setup Initial MdBook, User documentation --- docs/.gitignore | 1 + docs/book.toml | 6 ++ docs/src/SUMMARY.md | 18 +++++ docs/src/assets/youki.png | Bin 0 -> 10693 bytes docs/src/developer/introduction.md | 1 + docs/src/user/basic_setup.md | 99 ++++++++++++++++++++++++++ docs/src/user/basic_usage.md | 110 +++++++++++++++++++++++++++++ docs/src/user/crates.md | 3 + docs/src/user/introduction.md | 13 ++++ docs/src/user/libcgroups.md | 66 +++++++++++++++++ docs/src/user/libcontainer.md | 35 +++++++++ docs/src/user/liboci_cli.md | 24 +++++++ docs/src/user/libseccomp.md | 3 + docs/src/youki.md | 39 ++++++++++ 14 files changed, 418 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/book.toml create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/assets/youki.png create mode 100644 docs/src/developer/introduction.md create mode 100644 docs/src/user/basic_setup.md create mode 100644 docs/src/user/basic_usage.md create mode 100644 docs/src/user/crates.md create mode 100644 docs/src/user/introduction.md create mode 100644 docs/src/user/libcgroups.md create mode 100644 docs/src/user/libcontainer.md create mode 100644 docs/src/user/liboci_cli.md create mode 100644 docs/src/user/libseccomp.md create mode 100644 docs/src/youki.md diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..7585238e --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 00000000..ab52e4c5 --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Yashodhan Joshi"] +language = "en" +multilingual = false +src = "src" +title = "Youki User and Developer Documentation" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 00000000..1642b6c5 --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,18 @@ +# Summary + +[Youki](./youki.md) + +--- + +- [User Documentation](./user/introduction.md) + - [Basic Setup](./user/basic_setup.md) + - [Basic Usage](./user/basic_usage.md) + - [Crates provided](./user/crates.md) + - [libcgroups](./user/libcgroups.md) + - [libcontainer](./user/libcontainer.md) + - [liboci-cli](./user/liboci_cli.md) + - [libseccomp](./user/libseccomp.md) + +--- + +- [Developer Documentation](./developer/introduction.md) diff --git a/docs/src/assets/youki.png b/docs/src/assets/youki.png new file mode 100644 index 0000000000000000000000000000000000000000..40da2062b0d2b88f2603a753e66ac1058d9e440f GIT binary patch literal 10693 zcmY*S|ARcWgg ztyIMlv=JIazFq7kMJ%x-Q(Np?NDz_V$JVq!fO3br6HV-^Oz(W z*_q_d;=pHkWSy?Hrt+AgO_~rkWnxv`H3M-Gf;KZAOZUSkslUR1M2o#7l3Fc}4V)us=0&W8X^G#9`m`x_uIb->r_H@- z)-WF$J8%8^8mNw2dqW^3s(N4 z^Xmy!Sb7L0zWM*Adp&HQR~Y*Ncl25O{)ozJ_TK44b31q%sQPN$-i3_Jyg|LD7u9uO zhk<2UL;d6R@9w9)1C08JRq%J3$!8=FA#~5Be@Z~0<}qEWg|%f8gv8%@%fyP z#3mO6Y4{7&dXAW)h0?Y}d3Q1LS?l;ym30>pdtmiahF4)8)g>ML8)z3 zL)m!EGIyQn(!{@!#lN><9;MnoFTmZzOFYyYoHsopcES6rGY$k7Em{WXOZMycT&Z6P z=}Tv=FRm;QEw`qpB^$`K>8I^9b@ zfy-KIi|eh{ndXNf^ph0g-t4XK6k#$kI=|zC)-vn;Xj(w3xzy;X?A~sJfKj;@>X%H~ zc0jGcb-&nMpX)2@=5h!kU4Rd>2t-$RQbUR&GQX47qVMwaz8OX}F@+rX^ARZGqVdhi zS(_#GOWclc2Pr>CoJ18J%N`2d$0d+COcaYY&jCx4%iZAX&^n2S4MDtaNwLhY_A{Y-0~alORfi>`gcGWPR8KHl#;l;Zgwr*|YzLr0m2Z0?)q zDE)kvFr~SYbUCKT4;q7f>6J9n-Ac1rVgDfa!e}Y=hn-kZJ?R7Z!FXDC)oE$&W~aFz zU&1I_t#?*Zi5fqczv_ti6b!Yr--RCV)8TwPqP!z#&7Yp{H^K0kRknHF$r&GA)^O%* z>0-bzjgwEmAtB2BvNJmcFH`j@MZJywTheJMg$9-~OLa7IPDe+4T#ME5l?QU^uMso# zxdpuk`!aI&HW;Hq{RZPX|7E386dysFA5}_}Z?^4AVWQ&YUNrF}Qn?m{A|=ACtiJg8 zz&OTE{Qth+=Do}l+*!9zXxF)0mf}g;mbMXB(?3ntlx6bK?ZKHwt=HV6EW1hrgxB>i z!9>1y{D>t$5z0{2bT2=BKd+LR=&A#bjY(W~>C_Px%>D-Ox9gDqg|K_jtXb`0lzpW^ z@q41*&DX6L{=mtT(`)?f2g?m$=~iA)Wf*giLkkz2Kf5RA?v5ka-afQ_MiD;gDaF$% zT)RENSI|GSNf>QhXiqzBH}X05E-ZnnFd|oG1uxN6#HQ^Ov$&p z_dR!6z#?kZle`V5Wz|T(=w$Wjr+2Dsy%D+Kmf|*1`?|Zmk~WsMt^AKw(mved0z?Ks zMN1B%NXol0vx=iFe92#{qID=b57|rO{lh&(T;$P+l{%#uq3RMdY{`;|2u{5?{}4hl zN>bl=tJk>{JWJpi`UnT#+IKyq+;WZ!eimZ%mFPNxy=lF%7C_8hL29=Kj$F!m@(7_X zDMaXovXb$C7)DzaOMu+{!9iY^q$eSwRA8cl;_CW=gA(6dbY`n+Xq*c-|s{{k=#!-o=zEQ&A}V~YzrD3jt_&#jd*GwuD(jo zUuHya+1rw|k`$WNgu)S=l|G37cXoaQ-@)qEMvl~f;>wyu=Op$M3yX>Ln!hLpIj5py z>?0;qvLP8qd0(F06uM(U^`?RKYA}U{67k_zSeTQT>1FTuh9ebByI););KNl;Q~2`21#o^P4zmi^%#pKIyc=)t$(9 z)8hu+fYN0mtOOqv(uGoItk;`!yO$=C!E5Z9rbw^#`A#2heRFO!+_S&l*N|Cl=-rjG zkhg}KS_3(qNCGRyWq*9JDvImmMl2|q5pR?G?xflQYeSg8XsSgo7YZl1ra72zHWUpk; z*E_!civo2rhRM9H%8^F2r!}{_hSL9z4DN$@C^q~v>Y|ZzL07wA^9i`WUO=RJuDO z7`mw_x|f}PsM?zl#7d0)J$3;sG=r}S?>U`%lrNp^mAcU+ON-=LHfDsP?qPo<~JtsRep(6@gVh{^PiYsb zm50+e7$~j;rJ=$0xhRf*;|>jYbM=tJG)|G1U~FRvex(riSdsr{+JJ?0m0uea5zxpa z8y5dwuC4yL%X8$?jx8N$W{*!Rm!z1Y=pRoR%9D9RQiF6Ql8vwz^z_$H%&WirZij0Y z=gFk*tu2u--r>5Ts%FaZX?G;1gAcApt*8dVR95jti=~NL$WrGy^1Va*V5`;`0y}ul z&@l|0Szi)at;O7NJLfY#*21t-y%^e9K?8GI?jx&QnmhvSH26{68HPhB`rhKw!hNh( z=&ckpZEroHUKN*Y@!^E}w>#hI!O9b*jEVdjeA+)5;cuK#^Q^o(mj4#*E(V2FEN-a<+r7lTAx7 z*C_e_-X$f!1Ef7DMOnLpQAG>1)V12v()}up2695d4*Zy(8FqF!f-_1LZK|55FdVhA zMn;v2i~Q{5jGBik+H}lMdtN?cTC8$`23i?%AU}?kw9aJ*q&DFW5ekp?&fbDOfh(mJ z`^S#A;8g~f0)-%#Zx$36gX~c0za#L854f%#`{AFJz8@ImaAzJi)v36%_boibD%fP@ zeV>~GD5#seo#t&GmGw50KYMS{u(;1pN8y1NMVOaNIq@(&w7d`2xzYT*&*LhM?H^=b zt4`l}Tp1UX-z7*caaFf2S0zIAwm~%zO#v=JI33SvI3Q!tn0o5VkLs#c3Kf z&`ZrG=eh8{P=#KC6Z(qL0b|v&+0ma)JhPZ;7rxZYEnAmbT)|E&va-uSBp~m0v{_@QgLDV9M z@iya}n;XncCEDQI6D5Fzr6dlj-H2K_Hqs64g?&<$j^nm{ZUKea;kf?Qgpuk^Y#qO~ zop)U}E<1mr#h|Nn9oLDM5V=f)`%Eh-ntLej1R&KHuOX{8hYfJfLualleJqyJy-!U$ z-Ttit)W`=-=1;#m=hRbmT^Y)}b4pq-wQ*oTod*T`$o`VeO646^Xb#yW=%cJ<7p(dJ z+VmE4V^$MG+`(J_E>Yi(pL^5U^CByEs9Yqox*D*Z^tZOM8Y{CmT(xz~7B-g@5MG7bxg%`; z0YotSgwWH4r}uPCe(CO$(y`O&0IliP-P~9s=!GsY28o3OL}ytWNdCecb|Gwsd@m;T z6Q6m51s}Rq`r$Sw-!n@<$PVYdHTp=BQB8E+6n!m%6;gX~hCI$+XEe@)T+86&!*GE# z)%am%)8u-v=?)*iOaN(&KU{BVvZ9XU>Xsuy9JokAHYB8XnAy@tDC*Z;eKr^)C<}X3 z0=UMsm}?ni=2Yj>;LXYDH#9d5j0k6UW9-n64P zu4SNTs#xQ`>reBWW7C1ZI+ftS0t@O%)$Bs%ejd{@R^ZR-NLRHGQWO$_iVkWc;v?Hx zv(xq|755}6on+!585tDNwWoegd7i~>!u{X<``y>}K-u%c9LYfIlYCE@5}_bv$qTbK zHPfUY8zY=t0+4Qn+gNcF8Tk>bGnr_dE$bYbjS8tplZLQ)D>DHBbnU`I}Y zm+f$9XqKPDiV-S=_DHQh@pGO<^vCGd$>r(9r}4gnkNs(K4LXu26f8)la-rWoSTbDFFtYW526Cu3p5no@&QkTw$lbL>kWkk%f@HV zTMmSu2jXY>f9;mPdb1&@KBb>lE2`P9IPa24ipPoi6D0>wFeGUpG%H{ob(=GN?13KG z*4M_@o`eV&OcE7Ux;f;s#BN;GCH=a{n7l5ANVR&?Bo!Kz;2K@m7g}BQ1I?V0@*D1G zGa5}CjBomeUuY+H(p+Td_G~80zxloX6oU4YRs9;7|uZmCc?CZ?Tyt`ZOM0bxKmzy~^6Z!z(}= zDj#~XvtV8t=Ga3{ISL1&p>QBf5_+8mDs?_SFl~zwQp?nY3z!WsKw^lvx?P_=jkLpk zNUH6w>Xk-IW(8D4f>1$_-lPl2hfqMxJM0-~-O2SD+?T~&Z`@B&?x)`&xPZ%S3tJxUjyCVmrQ5P$F)p?=mwcFje zmQfrR!X3OD1#!NZ7AS439UME~hVVL8I{ob3&UG`*xw?bb>Qn{m9}xGG?75`Z}rLwP}`#2j(F@nmiFZs3cgmzK7#-E!T800wjV(!{?a>+R2iPl*Xsj z>Tj>C|5rCheS0uY!dr39?Fe_ICJ)Omf}dhlQT=uFQu}cPlF`5bqHrRNLUOSM?E>n{ zDwo(+0|OvRg9rtkDfo&)?=XS{Z(fH*LAzI(=CtqFt--a-2Lw~jA8k1^eM1iI#z=Yn z^dv$n2+C3nZTMi*I-s3Ox~|Fd|H6e;Ra7I|$%MWbqHF(_d($e?yB~`;nI1#Gm7oxY z;ZnOV+-ozRp(uBgkUXS8kYszUE&93w zxih_WF6)SdzVdoTxFAo^Q(mryVdn*7g;264!iR*Qp_=HZqnUFC+AQo;<=}WQcWtM#!YT@0~3ufUcj~z$T8gFR$hJFxMB4ZEXF!5DdFy z18#d4Iq<<$3W=8LBo~CfLlwDis;YGF0`Ml$K>haA@R6<`UriJAQbz*2IIFXa{^G)s zWMAtA3L|$2sT{7VU&n+Nx%xotaLWkA2;n~7I%JSMPVJPWT5KT_$}Ks7pjife-XKyJ znM(&2UB=aU_{01kciHl!_3;Yg3blT`x$W{iC2DnR&EzDPGiw@{foeC_7^nKIWB1cy zsZ+O1zWj>_s1xQ;OyQ;(_;p@tn%kShD8(n-$)erlnXU!DtBiN6V*t_@GR_Y2eYQH= zWXb~<7f1^r&M0oBk@@WqFq*Rnq>sJQ8~EuFMW|={`?+(nhFm99S%Id3o{nW(l`U~s zI6}Ay-lTZ}7MTq+0B#%BObD*N zrtVOrX2h)93E9~HYUyCYv@ZNe>=K(=hpyuRr6RId_r0$Nd~(b)nw$C*boE2_HMwZ{ zs=jA%CVK`5fwqjiX}2+EcX3f^SBiS83$9GY=8?W!I!Si35E?K#~E;VLQpj9>aD7 z=L}lxdeN&H%o5u)E8Z(=BJ-*6#p`I|3XTe9`b~arKe_LhsprLQ&4a9sE&7aYYXg6r z#>b7^blPjKp(H9>6F}*cMF(^W*$(w6;p9ofVi3?5ERWKYo-|2?jj86sW#axR=dZO~ zmZDewlw|(2Pj{#usF40%s!pO9VYmfeUSRYbWi+qoPHRi!shdEHPtSjtLyR~RU6k^$ zt+n4}$0&d$4z!kyZ!05s+TAvp8~%#}JyQZ7uZ^{}yq}qh;UT^@Bk+B5chhV?`qIsC zKYb1|ehKw5?6Fu0!Z`ckT=;-Ac>YSqJx!vRMW57JkKNDn+$FF zW56PvS+{RqFePc57qTl0Vv9=0W~Vl{f*Ozn5^xOXr0rB|v|q(t;jZub*&--pg#u68oLvG{RqUIR4~OJr z&{R-eJDH^0d2W5oCy$EW?1(py1>*xV_=gLn+)4_d?a0*PkF~&TrCg1*-3@g&Bx3hY zJ<<;R{-K%Qvuh13PUmgnic|;%CFtKdjdOK2>di7S#k8$Ilh)OhK(bD5g^w;VBnRO% zLLviP!|R@DN*^-wc&+$Er8~8T2KBr0403Z4P?U4zpv!bO1JN@$UED8R((%$3R=;Xk z&<2A`{Ajcs3JCeBe=w{?a8?mXSFJ$Jj-me)Y&XZgY@@exv=4UGlgS=TWd}z=V`P1@ z`M8b*bKGr1?;TW_;kiMnr=8KvG9deSXP{DnTHulUDX%yGQdsyvT9>Ce*|y0tborBS z7LVLZv5|Y+$tmca43&f;T6T<-nV)0G#GTbynsDWEH=P`8d{eQ-ZOcqgi-bLW3+`%D zDJPK6DE^eJ9eOD&F6h*g)Q-Nh?NWUT z`sYe$uLwNh5uwz;A)(<@z;1Hx-UaqlqL!`4cD07o3uP^%pJoK@x>mO`DlIVX;X5Xe zTNtQbCaI6FsTlV8cF-T&b{XQnMqp~s#93Q$Erc3fF!gwUx0 z_V9deQu`=-z5ynOjZ_^T%HL|>vS&qut|^Z(Gyx%`y^-83fIKI9IBN176+^OLYyRf2 zp6gyS&X2mB^~_kLYk*EJ+;y|#JoIQG-mnmBGmq4}A2JNo&*qixcvS&oGG+43)Z-Er zNbb=cEziBrI_38 z@J{ZXexe_y16wqIbWTXVUYoB3DA<9s#wyi^fo}6ZIoXhiCjG)!;v5_bOhIop=PnrM z)=Dc}ZgCTh`DIRodfhHYg$ikaL_!95_}3}mxO1iCw4~1tdW@D>eZTOl`XxqrTVIlG z(-XbBdJoV#!21i5c3onE0B`p}Uvn^+H(jg18%XX9q&zZA?<@wUxAkPa7He8W$n-BPyj(+0Fnu*y1G-xtwO2H=0c(@<&46b2rTKZ|$b<8s? zL=q!RFxL@@k{WMXb4uFcl{4cAr@8e_!zPW|I}#&_&}zsn=)=e&=SRlTXl~8Ll^g7O z6=ko>J!Eg&Ri*q6LlL*V`iRBJzfT_!8V;~I_ju?q!5UBicZP=;=iAH!jRDLW^0hq@ z=qgT*F=0R}Czv*4)fJv){|3xHEqd(ZuMq)sqdH@8kh=sX8hS%94!zhz1qmTKb?d9; z9$+*#m35Fjfj>BmOyqLvoQNf-XNr&VcvgwZTLGhM3txm zZwO>Bol}g@Zi)dUgeCe#zIvq}tAnyI=f;5nSE{!KjRg)A-l=x`IZ04q^xX<2+iM`7Z`5#lD0o8N2xLL;WcphGUspcQ|QO+ca2x?~1B%BFRx zxQ{Q|L_`P7aifwmb6GfiMT&jCL?!ShtIVatkD)39u!bu#-{~=q1w4Es8N*P)Myxu8 zaCKq&;KGbk%+ly#B9E=S%0ARVOb6zehnlyyLXLaW>ILAChlSbD^K@ye&`T=CN`?iD zxj0}73TwmTi4(lK-mPcF=6#}^dtMrq4b%ASs2Gq9ML6t%`9S(svHdq1>ysIun4B;= z6N`+RnBiU)j6~l zcjP=gSvGAM3r^pp#g~B>)C4SHXMXx%s=u=k5@ikCmVo*NBJJ-`+PWO5-pU{(=lA7E=XFe$c@l40 zZ`QCQJrp7)uJ5ExX%zMnQHW4(c$W6^4`XTn%Dq!56cD_e{1O`0 zyCs#F)5^zm6U~o{sNy5`r)YWVqiAhCThi$PU_9E+y+c7g|QN2cGl+oJY#^kJ^K3H$F78AL@G18X z3RGKz@Vn)1pX%>%A$B>Pet2Wm^pqrXl=u0JW70e63~1g|UjGzCJfV9R-o$k1M3Q3D+=r+wkabgdz3D%*wEf>0^CNZ!3EN~Ug=HPo5sSBh4|zM$ z8Jq=A*wyc9|G0Qd)J*|4dfwp$U^~KVS4B+L@R%7b#byS2VYsHR#AasEt$tOsAe6Og z{TyeV5g?oF;TX9F_0xCK$F*T4oap=WL`;wXGJOdE6Ds+|4r=j|v^`NTQ!DS8o~$Si z3#KbJJe9P~<+8`r3BuGL#3T*B4hqzAw804L=NSxO+z&<2PJ;ZdgjU^hD!+!g_%?SZ zc-YsED$LXtEE5Bk_;`tM$*erMp@nCfYvn=qlAdUpW*+c#&2^*5^PQ8h3_ol7e!&U$ z;R9mYieGobe59^4Gpzv%XOekgdXj^!vqxIZE4)mvh*>&YVsWj9h{vk5 z)1!`v-X%n4>}i61-eA4b-~u%y2tBMP9n8|`B@94NfBI*myxd^gs6*R zFmXlqHsTauW0Huy}86bx4CFt JcJ}Ju{|{f(_nQC! literal 0 HcmV?d00001 diff --git a/docs/src/developer/introduction.md b/docs/src/developer/introduction.md new file mode 100644 index 00000000..4796167e --- /dev/null +++ b/docs/src/developer/introduction.md @@ -0,0 +1 @@ +# Developer Documentation diff --git a/docs/src/user/basic_setup.md b/docs/src/user/basic_setup.md new file mode 100644 index 00000000..dc1c1d46 --- /dev/null +++ b/docs/src/user/basic_setup.md @@ -0,0 +1,99 @@ +# Basic Setup + +This section will explain how to setup youki for use. Currently the only way to get youki is to compile it from the source. Currently youki only supports Linux systems, so this documentation assumes you are using a Linux system. For running youki on other platforms, you can use Vagrant, which is explained in the last part of this section. + +### Requirements + +youki is written in rust, so you will need rust toolchain installed to compile it. Also if you want to use it with a higher level container engine, such as docker, you will need to install that as well. In case you want to use one of the sub-crates of youki as a dependency, you may not need docker. + +The rest of document uses docker as an example when required. + +- Rust(See [here](https://www.rust-lang.org/tools/install)), edition 2021 +- Docker(See [here](https://docs.docker.com/engine/install)) + +Apart from these basic requirements, some other libraries are also required to compile and run youki. To install them on : + +#### Debian, Ubuntu and related distributions + +```console +$ sudo apt-get install \ + pkg-config \ + libsystemd-dev \ + libdbus-glib-1-dev \ + build-essential \ + libelf-dev \ + libseccomp-dev +``` + +#### Fedora, Centos, RHEL and related distributions + +```console +$ sudo dnf install \ + pkg-config \ + systemd-devel \ + dbus-devel \ + elfutils-libelf-devel \ + libseccomp-devel +``` + +#### Getting the source + +After installing the dependencies you will need to clone the youki repository if you want to use it directly : + +```console +git clone git@github.com:containers/youki.git +``` + +Or if you want ot use it as a dependency in a Rust project, you can specify it in your Cargo.toml : + +```toml +[dependencies] +... +liboci-cli = { git = "https://github.com/containers/youki.git" } +... +``` + +You can specify the crate that you need as a dependency in place of `liboci-cli` + +#### Installing the source + +If you have cloned the source, you can build it using + +```console +# go into the cloned directory +cd youki + +# build +./build.sh +``` + +This will build the youki, and put the binary at the root level of the cloned directory. + +When using it as a dependency, you can use it in your source as : + +``` +use liboci_cli::{...} +``` + +You can specify the crate that you need as a dependency in place of `liboci-cli` + +#### Using Vagrant to run Youki on non-Linux Platform + +you can use the vagrantfile provided with the source, to setup vagrant and run youki inside it. You can see [vagrant installation](https://www.vagrantup.com/docs/installation) for how to download and setup vagrant. + +Once done, you can run vagrant commands in the cloned directory to run youki inside the VM created by vagrant : + +```console +# for rootless mode, which is default +vagrant up +vagrant ssh + +# or if you want to develop in rootful mode +VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant up +VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant ssh + +# in virtual machine +cd youki +./build.sh + +``` diff --git a/docs/src/user/basic_usage.md b/docs/src/user/basic_usage.md new file mode 100644 index 00000000..560c2cb0 --- /dev/null +++ b/docs/src/user/basic_usage.md @@ -0,0 +1,110 @@ +# Basic Usage + +This section will explain how to use youki as a low-level container runtime with some other high-level container runtime such as docker. + +Youki can also be used with other runtimes such as podman, but for this section, we will use docker as an example. + +#### Using youki with a high-level runtime + +This explains how to use youki as a lowe level runtime along with some high-level runtime. For this example we use Docker. + +1. If you have the docker daemon running (which you probably have if you have installed docker), first you will need to stop it. For example, if you use systemd as your init system, you can use `systemctl stop docker`, with root permissions. +2. Start the docker daemon with you as the runtime : + + ```console + dockerd --experimental --add-runtime="youki=$(pwd)/youki" # run in the root directory + ``` + + This will start the docker daemon with youki as the low-level runtime. This will keep the terminal busy, so you can start it as a background process or open a new terminal for next steps. + + In case you get an error message such as : + + ``` + failed to start daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid + ``` + + This means you docker daemon is already running, and you need to stop is as explained in step 1. + +3. Now you can use docker normally, and give youki as the runtime in the arguments : + ```console + docker run -it --rm --runtime youki busybox # run a container + ``` +4. After you are done, you can stop the docker daemon process that was started in step 2, and restart the normal docker daemon, by using your init system, for example using `systemctl start docker` with root permissions, for systems using systemd. + +#### Using Youki Standalone + +You can use youki directly without a higher level runtime, but it will be tedious. This example shows how to create and run a container using only youki. + +1. run + + ```console + mkdir -p tutorial/rootfs + ``` + + This will create a directory which will be used as the root directory for the container. + +2. run + ```console + cd tutorial + docker export $(docker create busybox) | tar -C rootfs -xvf - + ``` + This will export the basic file system structure needed to run the container. You can manually create all the directories, but it will be tedious. +3. run + ```console + ../youki spec + ``` + This will generate the config.json file needed to setup the permissions and configuration for the container process. + You can manually edit the file to customize the behavior of the container process. For example, you can edit the process.args to specify command to run in the process : + ```json + "process": { + ... + "args": [ + "sleep", "30" + ], + ... + } + ``` + Then go back to the root directory : + ```console + cd .. + ``` +4. After this you can use youki to : + - create the container + ```console + # create a container with name `tutorial_container` + sudo ./youki create -b tutorial tutorial_container + ``` + - get the state of the container + ```console + # you can see the state the container is `created` + sudo ./youki state tutorial_container + ``` + - start the container + ```console + # start the container + sudo ./youki start tutorial_container + ``` + - list all the containers + ```console + # will show the list of containers, the container is `running` + sudo ./youki list + ``` + - delete the specific container + ```console + # delete the container + sudo ./youki delete tutorial_container + ``` +5. The above step created the containers with root permissions, but youki can also create rootless containers,which does not need root permissions. for that, after exporting the rootfs from docker, when creating spec, use `--rootless` flag : + ```console + ../youki spec --rootless + ``` + This will generate the spec needed for rootless containers. + After this the steps are same, except you can run them without sudo and root access : + ```console + cd .. + sudo ./youki create -b tutorial rootless_container + sudo ./youki state rootless_container + sudo ./youki start rootless_container + sudo ./youki list + sudo ./youki delete rootless_container + ``` diff --git a/docs/src/user/crates.md b/docs/src/user/crates.md new file mode 100644 index 00000000..3a6320b2 --- /dev/null +++ b/docs/src/user/crates.md @@ -0,0 +1,3 @@ +# Crates provided + +The github repo of youki is a Cargo workspace containing several crates, which provide various functionalities : for example, libcgroups provide means to work with Linux cgroups. Youki itself is one of the crates, and uses functionalities from the other crates. The following sections explain the crates and public interfaces provided by them, as well as commandline interface of youki itself. diff --git a/docs/src/user/introduction.md b/docs/src/user/introduction.md new file mode 100644 index 00000000..6dd167c3 --- /dev/null +++ b/docs/src/user/introduction.md @@ -0,0 +1,13 @@ +# User Documentation + +This section is the user documentation for youki, for using it as a low-level container runtime. +This section will explain : + +- Basic Setup : Explains how to setup youki for use +- Basic Usage : Using it as a low level runtime +- crates +- libcgroups +- libcontainer +- liboci-cli +- libseccomp +- youki diff --git a/docs/src/user/libcgroups.md b/docs/src/user/libcgroups.md new file mode 100644 index 00000000..c1320c33 --- /dev/null +++ b/docs/src/user/libcgroups.md @@ -0,0 +1,66 @@ +# libcgroups + +`libcgroups` provide a Rust interface over cgroups v1 and v2. + +It exposes the modules : + +- common +- stats +- systemd +- test_manager +- v1 +- v2 + +### common + +This module contains common features for cgroups v1 and v2, such as + +- trait CgroupManager, which gives public interface to + + - add a task to a cgroup + - apply resource restriction + - remove a cgroup + - freezer cgroup state control + - get stats from a cgroup + - get pids belonging to the cgroup + +- functions `write_cgroup_file_str` and `write_cgroup_file` which writes data to a cgroup file +- function `read_cgroup_file` which reads data from given cgroup file +- function `get_cgroup_setup` which returns setup of cgroups (v1,v2, hybrid) on the system + +### stats + +This module contains structs and functions to work with statistics for a cgroup, such as + +- struct Stats which contains all following individual stat structs + - CpuStats : stores usage and throttling information + - MemoryStats : stores usage of memory, swap and memory combined, kernel memory, kernel tcp memory and other memory stats + - PidStats : contains current number of active pids and allowed number of pids + - BlkioStats : contains block io related stats such as number of bytes transferred from/to by a device in cgroup, number of io operations done by a device in cgroup, device access and queue information + - HugeTlbStats : stats for huge TLB , containing usage, max_usage and fail count +- function `supported_page_size` which returns hugepage size supported by the system +- functions to operate with data in cgroups files such as + - `parse_single_value` : reads file expecting it to have a single value, and returns the value + - `parse_flat_keyed_data` : parses cgroup file data which is in flat keyed format (key value) + - `parse_nested_keyed_data` : parses cgroup file data which is in nested keyed format (key list of values) + - `parse_device_number` : parses major and minor number of device + +### systemd + +This module contains functions and modules to deal with systemd, as currently youki depends on systemd. This exposes + +- function `booted` to check if the system was booted with systemd or not +- module controller_type, which contains + - enum ControllerType which is used to specify controller types +- module manager, which contains + - struct Manager, which is the cgroup manager, and contain information about the root cgroups path, path for the specific cgroups, client to communicate with systemd etc. This also implements CgroupManager trait. + +### test_manager + +This exposes a TestManager struct which can be used as dummy for testing purposes, which also implements CgroupManager. + +### v1 and v2 + +These modules contains modules and fucntions related to working with cgroups v1 and v2. They expose respective cgroups version specific mangers, and some utility functions to get mount points (for v1 and v2), get subsystem mount points (for v1) and get available controllers (for v2) etc. + +For cgroups v2, it also exposes devices module, which gives functions for working with bpf such as load a bpf program, query info of a bpf program, attach and detach a bpf program to a cgroup, etc. diff --git a/docs/src/user/libcontainer.md b/docs/src/user/libcontainer.md new file mode 100644 index 00000000..5d1455c7 --- /dev/null +++ b/docs/src/user/libcontainer.md @@ -0,0 +1,35 @@ +# libcontainer + +This is a library that provides utilities to setup and run containers. Youki itself uses this crate to manage and control the containers. + +This exposes several modules, each dealing with a specific aspect of working with containers. + +- apparmor : functions that deal with apparmor, which is a Linux Kernel security module to control program capabilities with per program profiles. + +- capabilities : this has functions related to set and reset specific capabilities, as well as to drop extra privileges. + +- config : this exposes YoukiConfig struct, which contains a subset of the data in the config.json. This subset is needed when starting or managing containers after creation, and rather than parsing and passing around whole config.json, this smaller YoukiConfig is passed, which is comparatively faster. + +- container : This is the core of the container module, and contains modules and structs that deal with the container lifecycle including creating, starting , stopping and deleting containers. + +- hooks : exposes function run_hooks, which is used to run various container lifecycle hooks as specified in oci-spec + +- namespaces : exposes Namespaces struct, which deals with applying namespaces to a container process + +- notify_socket : this has NotifyListener struct, which is used internally to communicate between the main youki process and the forked container process + +- process : a module which exposes functions related to forking the process, starting the container process with correct namespaces and setting up the namespaces + +- rootfs : this contains modules which deal with rootfs, which is minimal filesystem + +- rootless : this deals with running containers rootless, that is without needing root privileges on the host system + +- seccomp : this deals with setting up seccomp for container process, this uses libseccomp. + +- signal : this provide simple wrappers for unix signal's ascii names/numbers. + +- syscall : this provides a trail Syscall, which is used to abstract over several functions which need to call libc functions, so that other parts of library can use them without having to deal with implementation details. + +- tty : this deals with setting up the tty for the container process + +- utils : provides various utility functions such as parse_env to parse the env variables, do_exec to do an exec syscall and execute a binary, get_cgroups_path, create_dir_all_with_mode etc. diff --git a/docs/src/user/liboci_cli.md b/docs/src/user/liboci_cli.md new file mode 100644 index 00000000..7fa5bac3 --- /dev/null +++ b/docs/src/user/liboci_cli.md @@ -0,0 +1,24 @@ +# liboci-cli + +This is a crate to parse command line arguments for OCI container runtimes as specified in the OCI Runtime Command Line Interface. This exposes structures with Clap Parser derived, so that they can be directly used for parsing oci-commandline arguments. + +### Implemented subcommands + +| Command | liboci-cli | CLI Specification | runc | crun | youki | +| :--------: | :--------: | :---------------: | :--: | :--: | :---: | +| create | ✅ | ✅ | ✅ | ✅ | ✅ | +| start | ✅ | ✅ | ✅ | ✅ | ✅ | +| state | ✅ | ✅ | ✅ | ✅ | ✅ | +| kill | ✅ | ✅ | ✅ | ✅ | ✅ | +| delete | ✅ | ✅ | ✅ | ✅ | ✅ | +| checkpoint | | | ✅ | ✅ | | +| events | ✅ | | ✅ | | ✅ | +| exec | ✅ | | ✅ | ✅ | ✅ | +| list | ✅ | | ✅ | ✅ | ✅ | +| pause | ✅ | | ✅ | ✅ | ✅ | +| ps | ✅ | | ✅ | ✅ | ✅ | +| restore | | | ✅ | ✅ | | +| resume | ✅ | | ✅ | ✅ | ✅ | +| run | ✅ | | ✅ | ✅ | ✅ | +| spec | ✅ | | ✅ | ✅ | ✅ | +| update | | | ✅ | ✅ | | diff --git a/docs/src/user/libseccomp.md b/docs/src/user/libseccomp.md new file mode 100644 index 00000000..521aeb24 --- /dev/null +++ b/docs/src/user/libseccomp.md @@ -0,0 +1,3 @@ +# libseccomp + +This crate provides Rust FFI bindings to [libseccomp](https://github.com/seccomp/libseccomp). This is adapted from code generated using rust-bindgen from a C header file. This also manually fixes some of the issues that occur as rust-bindgen has some issues when dealing with C function macros. diff --git a/docs/src/youki.md b/docs/src/youki.md new file mode 100644 index 00000000..6fd7749b --- /dev/null +++ b/docs/src/youki.md @@ -0,0 +1,39 @@ +# Youki + +

+ +

+ +youki is an implementation of the [OCI runtime-spec](https://github.com/opencontainers/runtime-spec) in Rust, similar to [runc](https://github.com/opencontainers/runc). + +## About the name + +youki is pronounced as /joʊki/ or yoh-key. +youki is named after the Japanese word 'youki', which means 'a container'. In Japanese language, youki also means 'cheerful', 'merry', or 'hilarious'. + +## Motivation + +Here is why we are writing a new container runtime in Rust. + +- Rust is one of the best languages to implement the oci-runtime spec. Many very nice container tools are currently written in Go. However, the container runtime requires the use of system calls, which requires a bit of special handling when implemented in Go. This is too tricky (e.g. _namespaces(7)_, _fork(2)_); with Rust, it's not that tricky. And, unlike in C, Rust provides the benefit of memory safety. While Rust is not yet a major player in the container field, it has the potential to contribute a lot: something this project attempts to exemplify. +- youki has the potential to be faster and use less memory than runc, and therefore work in environments with tight memory usage requirements. Here is a simple benchmark of a container from creation to deletion. + + | Runtime | Time (mean ± σ) | Range (min … max) | + | :-----: | :----------------: | :-----------------: | + | youki | 198.4 ms ± 52.1 ms | 97.2 ms … 296.1 ms | + | runc | 352.3 ms ± 53.3 ms | 248.3 ms … 772.2 ms | + | crun | 153.5 ms ± 21.6 ms | 80.9 ms … 196.6 ms | + +
+ Details about the benchmark + + - A command used for the benchmark + ```console + $ hyperfine --prepare 'sudo sync; echo 3 | sudo tee /proc/sys/vm/drop_caches' --warmup 10 --min-runs 100 'sudo ./youki create -b tutorial a && sudo ./youki start a && sudo ./youki delete -f a' + ``` + - Enviroment + `console $ ./youki info Version 0.0.1 Kernel-Release 5.11.0-41-generic Kernel-Version #45-Ubuntu SMP Fri Nov 5 11:37:01 UTC 2021 Architecture x86_64 Operating System Ubuntu 21.04 Cores 12 Total Memory 32025 Cgroup setup hybrid Cgroup mounts blkio /sys/fs/cgroup/blkio cpu /sys/fs/cgroup/cpu,cpuacct cpuacct /sys/fs/cgroup/cpu,cpuacct cpuset /sys/fs/cgroup/cpuset devices /sys/fs/cgroup/devices freezer /sys/fs/cgroup/freezer hugetlb /sys/fs/cgroup/hugetlb memory /sys/fs/cgroup/memory net_cls /sys/fs/cgroup/net_cls,net_prio net_prio /sys/fs/cgroup/net_cls,net_prio perf_event /sys/fs/cgroup/perf_event pids /sys/fs/cgroup/pids unified /sys/fs/cgroup/unified CGroup v2 controllers cpu detached cpuset detached hugetlb detached io detached memory detached pids detached device attached Namespaces enabled mount enabled uts enabled ipc enabled user enabled pid enabled network enabled cgroup enabled $ ./youki --version youki version 0.0.1 commit: 0.0.1-0-0be33bf $ runc -v runc version 1.0.0-rc93 commit: 12644e614e25b05da6fd08a38ffa0cfe1903fdec spec: 1.0.2-dev go: go1.13.15 libseccomp: 2.5.1 $ crun --version crun version 0.19.1.45-4cc7 commit: 4cc7fa1124cce75dc26e12186d9cbeabded2b710 spec: 1.0.0 +SYSTEMD +SELINUX +APPARMOR +CAP +SECCOMP +EBPF +CRIU +YAJL ` +
+ +- The development of [railcar](https://github.com/oracle/railcar) has been suspended. This project was very nice but is no longer being developed. This project is inspired by it. +- I have fun implementing this. In fact, this may be the most important.