From 4451cff7bcb022b669ab13307c523de5c3b5bb7b Mon Sep 17 00:00:00 2001 From: Scott Daniels Date: Tue, 17 Sep 2013 10:42:35 -0400 Subject: [PATCH] Initial push of doc and related files to repo. Change-Id: I28871653dfe14f219c5fc140fc84a9a01e6fcda7 --- doc/source/.gitignore | 6 + doc/source/global.make | 17 ++ doc/source/ic_user/examples.tex | 18 ++ doc/source/ic_user/ic_user.tex | 47 ++++ doc/source/ic_user/inception_final.fig | 100 +++++++++ doc/source/ic_user/inception_planes.fig | 287 ++++++++++++++++++++++++ doc/source/ic_user/makefile | 32 +++ doc/source/ic_user/overview.tex | 36 +++ doc/source/ic_user/prep.tex | 153 +++++++++++++ doc/source/ic_user/running.tex | 189 ++++++++++++++++ doc/source/ic_user/start_overview.fig | 102 +++++++++ doc/source/ic_user/texmf.cnf | 3 + doc/source/ic_user/using.tex | 55 +++++ doc/source/macros/README | 2 + doc/source/macros/deflist.tex | 22 ++ doc/source/makefile | 29 +++ 16 files changed, 1098 insertions(+) create mode 100644 doc/source/.gitignore create mode 100644 doc/source/global.make create mode 100644 doc/source/ic_user/examples.tex create mode 100644 doc/source/ic_user/ic_user.tex create mode 100644 doc/source/ic_user/inception_final.fig create mode 100644 doc/source/ic_user/inception_planes.fig create mode 100644 doc/source/ic_user/makefile create mode 100644 doc/source/ic_user/overview.tex create mode 100644 doc/source/ic_user/prep.tex create mode 100644 doc/source/ic_user/running.tex create mode 100644 doc/source/ic_user/start_overview.fig create mode 100644 doc/source/ic_user/texmf.cnf create mode 100644 doc/source/ic_user/using.tex create mode 100644 doc/source/macros/README create mode 100644 doc/source/macros/deflist.tex create mode 100644 doc/source/makefile diff --git a/doc/source/.gitignore b/doc/source/.gitignore new file mode 100644 index 0000000..f591c12 --- /dev/null +++ b/doc/source/.gitignore @@ -0,0 +1,6 @@ +*.pdf +*.log +*.aux +*.eps +*.sp +*- diff --git a/doc/source/global.make b/doc/source/global.make new file mode 100644 index 0000000..c677032 --- /dev/null +++ b/doc/source/global.make @@ -0,0 +1,17 @@ +# global things needed by all make files -- mostly meta rules + +SHELL = ksh + +# allows the use of ../ in include statements +env = openout_any=a openin_any=a + +%.pdf : %.tex + $(env) latex -halt-on-error -interaction=nonstopmode -output-format=pdf $< + +%.dvi : %.tex + $(env) latex -halt-on-error -interaction=nonstopmode -output-format=dvi $< + +# xfig used to produce/maintain figures. this converts to eps +%.eps: %.fig + fig2dev -L eps <$< >$@ + diff --git a/doc/source/ic_user/examples.tex b/doc/source/ic_user/examples.tex new file mode 100644 index 0000000..1f40ff3 --- /dev/null +++ b/doc/source/ic_user/examples.tex @@ -0,0 +1,18 @@ +\section{Installation examples} +The following commands illustrate how each of the necessary software packages can be installed. +Your milage may vary depending on wither your system uses \verb!apt-get, zypper,! or some other +package management software. + +\small\begin{verbatim} + apt-get -y install python + apt-get -y install ipython + apt-get -y install pip + apt-get -y install sshuttle + pip install python-novaclient + pip install oslo.config + + cd $HOME/repo # any writable directory should do + git clone https://github.com/stackforge/inception.git + ( cd inception && python setup.py install ) + +\end{verbatim}\normalsize diff --git a/doc/source/ic_user/ic_user.tex b/doc/source/ic_user/ic_user.tex new file mode 100644 index 0000000..ac76369 --- /dev/null +++ b/doc/source/ic_user/ic_user.tex @@ -0,0 +1,47 @@ +%% Mnemonic: ic_user.tex +%% Abstract: LaTex source for the inception cloud user doc. +%% Date: 26 August 2013 +%% Author: E. Scott Daniels +%% Mods: 01 Sep 2013 : Converted from {X}fm source +%% ============================================================================================ + +\documentclass[letterpaper,8pt]{paper} +%\author{E.~Scott~Daniels} +\title{Inception Cloud User's Guide} +\usepackage{graphicx} +\usepackage{enumitem} + +% must bloody set environment vars to get ../dir/file to work in include. +\input{../macros/deflist} + + +%% ---------- end setup ------------------------ + +\begin{document} +\maketitle + +% ----------- main sections -------------------- +\input{overview} +\input{prep} +\input{running} +\input{using} +% +% ---------- back sections ------------------------ +% +\newpage +\appendix +\input{examples} +% +% ---------- end matter ------------------------ +% +\tiny +\vspace{3in} +\noindent +\rule{\linewidth}{1 pt} +\dlbeg{0.3in} +\dlitem{Original:}{August 26, 2013} +\dlitem{Revised:}{\today} +\dlitem{Source:}{ic\_user.tex} +\dlend + +\end{document} diff --git a/doc/source/ic_user/inception_final.fig b/doc/source/ic_user/inception_final.fig new file mode 100644 index 0000000..92282bb --- /dev/null +++ b/doc/source/ic_user/inception_final.fig @@ -0,0 +1,100 @@ +#FIG 3.2 Produced by xfig version 3.2.5b +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +1 4 0 1 0 7 45 -1 20 0.000 1 0.0000 6435 2835 142 142 6293 2835 6577 2835 +2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5 + 3600 4050 3600 450 450 450 450 4050 3600 4050 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 7020 3690 6480 3690 6480 3240 7020 3240 7020 3690 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 8460 3690 7920 3690 7920 3240 8460 3240 8460 3690 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 9180 3690 8640 3690 8640 3240 9180 3240 9180 3690 +2 2 0 1 0 15 50 -1 31 0.000 0 0 -1 0 0 5 + 2070 990 720 990 720 1890 2070 1890 2070 990 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 450 5130 4140 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6750 2880 6750 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 7470 2880 7470 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8190 2880 8190 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8910 2880 8910 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 1260 6480 1260 +2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5 + 7470 1530 6480 1530 6480 990 7470 990 7470 1530 +2 4 0 1 0 17 59 -1 30 0.000 0 0 7 0 0 5 + 9000 1350 8010 1350 8010 810 9000 810 9000 1350 +2 4 0 1 0 17 58 -1 30 0.000 0 0 7 0 0 5 + 8820 1440 7830 1440 7830 900 8820 900 8820 1440 +2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5 + 8640 1530 7650 1530 7650 990 8640 990 8640 1530 +2 1 1 1 0 7 45 -1 -1 6.000 0 0 -1 0 0 2 + 6120 1710 9900 1710 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6570 3960 9090 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6750 3690 6750 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 7470 3690 7470 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8190 3690 8190 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8910 3690 8910 3960 +2 4 0 1 0 22 50 -1 30 0.000 0 0 7 0 0 5 + 8730 2520 7740 2520 7740 1980 8730 1980 8730 2520 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8100 2520 8100 2880 +2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5 + 9900 4320 9900 450 6120 450 6120 4320 9900 4320 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 2880 6300 2880 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 3420 6480 3420 +2 2 0 1 0 6 50 -1 31 0.000 0 0 -1 0 0 5 + 3330 2790 1980 2790 1980 3690 3330 3690 3330 2790 +2 2 3 2 31 31 54 -1 35 1.500 0 0 -1 0 0 5 + 6390 3060 9630 3060 9630 4230 6390 4230 6390 3060 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 7740 3690 7200 3690 7200 3240 7740 3240 7740 3690 +2 1 0 1 0 7 45 -1 -1 0.000 0 0 -1 1 1 4 + 2 1 1.00 60.00 120.00 + 2 1 1.00 60.00 120.00 + 3325 3172 4765 3172 4585 3352 6475 3352 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6570 2880 9090 2880 +3 2 1 1 0 7 49 -1 -1 4.000 0 1 1 10 + 2 1 1.00 60.00 120.00 + 2 1 1.00 60.00 120.00 + 2076 1413 2925 1800 2719 3069 4305 3595 5792 3715 6805 3307 + 6774 3795 7223 3871 7533 3826 7631 3538 + 0.000 -1.000 -1.000 -1.000 -1.000 -1.000 -1.000 -1.000 + -1.000 0.000 +4 0 0 50 -1 4 12 0.0000 4 150 1125 630 720 Workstation\001 +4 0 0 50 -1 4 12 0.0000 4 180 2295 6390 720 OpenStack Environment\001 +4 0 0 45 -1 4 12 0.0000 4 150 330 6570 3600 Gw\001 +4 0 0 45 -1 4 12 0.0000 4 150 225 7290 3600 Ct\001 +4 0 0 45 -1 4 12 0.0000 4 150 285 8010 3600 Ch\001 +4 0 0 45 -1 4 12 0.0000 4 150 300 8730 3600 Wk\001 +4 0 0 45 -1 4 12 0.0000 4 150 735 810 1530 Browser\001 +4 0 0 45 -1 4 10 0.0000 4 120 765 6570 1260 Controller\001 +4 0 0 45 -1 4 10 0.0000 4 150 765 7740 1260 Compute\001 +4 0 0 45 -1 4 10 0.0000 4 120 330 8010 2430 VMs\001 +4 0 0 45 -1 4 10 0.0000 4 120 510 7920 2160 Other \001 +4 0 0 45 -1 4 10 0.0000 4 120 1215 8190 2790 Virtual Network\001 +4 0 0 45 -1 4 10 0.0000 4 135 1980 6930 4140 Private (control) Network\001 +4 0 0 45 -1 4 10 0.0000 4 120 360 9360 1620 Real\001 +4 0 0 45 -1 4 10 0.0000 4 120 510 9270 1890 Virtual\001 +4 0 0 45 -1 4 10 1.5708 4 150 750 9360 4050 Inception\001 +4 0 0 45 -1 4 10 1.5708 4 120 495 9540 3960 Cloud\001 +4 0 0 45 -1 4 12 0.0000 4 150 675 2430 3240 sshuttle\001 +4 0 0 45 -1 4 10 1.5708 4 120 1185 5040 2880 Public Network\001 diff --git a/doc/source/ic_user/inception_planes.fig b/doc/source/ic_user/inception_planes.fig new file mode 100644 index 0000000..57bf06a --- /dev/null +++ b/doc/source/ic_user/inception_planes.fig @@ -0,0 +1,287 @@ +#FIG 3.2 Produced by xfig version 3.2.5b +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +6 6510 3550 7440 4613 +2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6 + 6990 4083 7440 3825 7440 4344 6986 4605 6986 4085 6990 4083 +2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5 + 6521 3816 6970 3550 7438 3827 6989 4085 6521 3816 +2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6 + 6515 3819 6984 4086 6986 4613 6512 4347 6510 3817 6515 3819 +-6 +6 7530 4120 8460 5183 +2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6 + 8010 4653 8460 4395 8460 4914 8006 5175 8006 4655 8010 4653 +2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5 + 7541 4386 7990 4120 8458 4397 8009 4655 7541 4386 +2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6 + 7535 4389 8004 4656 8006 5183 7532 4917 7530 4387 7535 4389 +-6 +6 8535 4720 9465 5783 +2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6 + 9015 5253 9465 4995 9465 5514 9011 5775 9011 5255 9015 5253 +2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5 + 8546 4986 8995 4720 9463 4997 9014 5255 8546 4986 +2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6 + 8540 4989 9009 5256 9011 5783 8537 5517 8535 4987 8540 4989 +-6 +6 6135 1540 7065 2603 +2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6 + 6615 2073 7065 1815 7065 2334 6611 2595 6611 2075 6615 2073 +2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6 + 6140 1809 6609 2076 6611 2603 6137 2337 6135 1807 6140 1809 +2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5 + 6146 1806 6595 1540 7063 1817 6614 2075 6146 1806 +-6 +6 5565 2950 6495 4013 +2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6 + 6045 3483 6495 3225 6495 3744 6041 4005 6041 3485 6045 3483 +2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5 + 5576 3216 6025 2950 6493 3227 6044 3485 5576 3216 +2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6 + 5570 3219 6039 3486 6041 4013 5567 3747 5565 3217 5570 3219 +-6 +6 5309 5688 6239 6751 +2 3 0 1 0 17 40 -1 30 0.000 0 0 -1 0 0 5 + 5320 5954 5769 5688 6237 5965 5788 6223 5320 5954 +2 3 0 1 0 17 42 -1 30 0.000 0 0 -1 0 0 6 + 5789 6221 6239 5963 6239 6482 5785 6743 5785 6223 5789 6221 +2 3 0 1 0 15 41 -1 30 0.000 0 0 -1 0 0 6 + 5314 5957 5783 6224 5785 6751 5311 6485 5309 5955 5314 5957 +-6 +6 6164 6213 7094 7276 +2 3 0 1 0 17 40 -1 30 0.000 0 0 -1 0 0 5 + 6175 6479 6624 6213 7092 6490 6643 6748 6175 6479 +2 3 0 1 0 17 42 -1 30 0.000 0 0 -1 0 0 6 + 6644 6746 7094 6488 7094 7007 6640 7268 6640 6748 6644 6746 +2 3 0 1 0 15 41 -1 30 0.000 0 0 -1 0 0 6 + 6169 6482 6638 6749 6640 7276 6166 7010 6164 6480 6169 6482 +-6 +6 7319 6858 8249 7921 +2 3 0 1 0 17 40 -1 30 0.000 0 0 -1 0 0 5 + 7330 7124 7779 6858 8247 7135 7798 7393 7330 7124 +2 3 0 1 0 17 42 -1 30 0.000 0 0 -1 0 0 6 + 7799 7391 8249 7133 8249 7652 7795 7913 7795 7393 7799 7391 +2 3 0 1 0 15 41 -1 30 0.000 0 0 -1 0 0 6 + 7324 7127 7793 7394 7795 7921 7321 7655 7319 7125 7324 7127 +-6 +6 7124 2078 8054 3141 +2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6 + 7604 2611 8054 2353 8054 2872 7600 3133 7600 2613 7604 2611 +2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6 + 7129 2347 7598 2614 7600 3141 7126 2875 7124 2345 7129 2347 +2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5 + 7135 2344 7584 2078 8052 2355 7603 2613 7135 2344 +-6 +6 8090 2595 9020 3658 +2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6 + 8570 3128 9020 2870 9020 3389 8566 3650 8566 3130 8570 3128 +2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6 + 8095 2864 8564 3131 8566 3658 8092 3392 8090 2862 8095 2864 +2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5 + 8101 2861 8550 2595 9018 2872 8569 3130 8101 2861 +-6 +6 9074 3178 10004 4241 +2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6 + 9554 3711 10004 3453 10004 3972 9550 4233 9550 3713 9554 3711 +2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6 + 9079 3447 9548 3714 9550 4241 9076 3975 9074 3445 9079 3447 +2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5 + 9085 3444 9534 3178 10002 3455 9553 3713 9085 3444 +-6 +6 10074 3811 11004 4874 +2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6 + 10554 4344 11004 4086 11004 4605 10550 4866 10550 4346 10554 4344 +2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6 + 10079 4080 10548 4347 10550 4874 10076 4608 10074 4078 10079 4080 +2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5 + 10085 4077 10534 3811 11002 4088 10553 4346 10085 4077 +-6 +6 11090 4378 12020 5441 +2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6 + 11570 4911 12020 4653 12020 5172 11566 5433 11566 4913 11570 4911 +2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6 + 11095 4647 11564 4914 11566 5441 11092 5175 11090 4645 11095 4647 +2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5 + 11101 4644 11550 4378 12018 4655 11569 4913 11101 4644 +-6 +6 3733 5514 10100 9204 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 3780 6713 8055 9182 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 8038 9175 10063 8005 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 5798 5551 10074 8020 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 3762 6702 5789 5532 +-6 +6 9958 5472 10867 5859 +6 9958 5472 10867 5859 +5 1 0 1 0 13 34 -1 30 0.000 0 1 0 0 10418.558 4256.279 9960 5791 10407 5858 10853 5798 +1 2 0 1 0 14 35 -1 30 0.000 1 0.0000 10408 5577 450 105 9958 5577 10858 5577 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10867 5578 10867 5798 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 9960 5571 9960 5791 +2 2 0 0 14 13 40 -1 30 0.000 0 0 -1 0 0 5 + 9964 5612 10857 5612 10857 5806 9964 5806 9964 5612 +-6 +6 10310 5496 10519 5649 +6 10310 5516 10519 5638 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10314 5519 10519 5638 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10511 5635 10490 5587 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10512 5635 10463 5638 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10370 5516 10316 5521 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10333 5577 10310 5527 +-6 +6 10312 5496 10494 5649 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10482 5558 10427 5562 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10437 5504 10423 5555 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10312 5649 10494 5496 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10392 5583 10377 5636 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 10392 5585 10338 5588 +-6 +-6 +-6 +6 4629 2917 5538 3304 +5 1 0 1 0 9 34 -1 30 0.000 0 1 0 0 5089.558 1701.279 4631 3236 5078 3303 5524 3243 +6 4981 2941 5190 3094 +6 4981 2961 5190 3083 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 4985 2964 5190 3083 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5182 3080 5161 3032 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5183 3080 5134 3083 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5041 2961 4987 2966 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5004 3022 4981 2972 +-6 +6 4983 2941 5165 3094 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5153 3003 5098 3007 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5108 2949 5094 3000 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 4983 3094 5165 2941 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5063 3028 5048 3081 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5063 3030 5009 3033 +-6 +-6 +1 2 0 1 0 10 35 -1 30 0.000 1 0.0000 5079 3022 450 105 4629 3022 5529 3022 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 4631 3016 4631 3236 +2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2 + 5538 3023 5538 3243 +2 2 0 0 14 9 40 -1 30 0.000 0 0 -1 0 0 5 + 4635 3057 5528 3057 5528 3251 4635 3251 4635 3057 +-6 +6 405 299 3250 8740 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 3232 319 3230 7134 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 439 8690 3235 7075 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 420 1929 3216 314 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 429 1910 427 8725 +4 0 0 40 -1 6 14 0.5236 4 180 1260 747 2173 Real World\001 +-6 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 3874 3314 9776 6723 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 6660 1710 12563 5119 +2 1 0 5 1 1 45 -1 -1 0.000 0 0 -1 0 0 3 + 5279 3901 8753 5913 8772 5880 +2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 6524 4593 6963 4340 +2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 5549 4011 5988 3758 +2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 7469 5190 7908 4937 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 9773 6714 12569 5099 +2 1 0 5 20 0 45 -1 -1 0.000 0 0 -1 0 0 2 + 2723 7216 2720 793 +2 1 0 5 20 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 2743 1845 5861 3645 5889 3597 +2 1 0 5 23 12 46 -1 -1 0.000 0 0 -1 0 0 5 + 9150 5500 10012 5979 8638 6765 8641 7993 7998 8379 +2 1 0 5 23 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 5246 6763 6058 6295 6056 6253 +2 1 0 5 23 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 6195 7257 7007 6789 7005 6747 +2 1 0 5 23 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 7302 7913 8114 7445 8112 7403 +2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 8537 5811 8976 5558 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 7142 3139 7548 2905 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 6056 3650 6998 3107 6970 3058 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 6163 2586 6569 2352 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 9158 5459 10100 4916 10072 4867 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 11090 5437 11496 5203 +2 1 0 5 23 12 45 -1 -1 0.000 0 0 -1 0 0 2 + 10004 5983 10284 5816 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 10460 5665 10968 5371 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 8056 4820 8998 4277 8970 4228 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 8049 3691 8455 3457 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 9052 4281 9458 4047 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2 + 10045 4863 10451 4629 +2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3 + 7027 4230 7969 3687 7941 3638 +2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 3849 3299 6647 1684 +2 1 0 5 12 12 45 -1 -1 0.000 0 0 -1 0 0 2 + 5059 3147 6093 2590 +2 4 0 1 14 14 30 -1 30 0.000 0 0 7 0 0 5 + 2340 8370 2115 8370 2115 8160 2340 8160 2340 8370 +2 4 0 1 17 17 30 -1 30 0.000 0 0 7 0 0 5 + 2340 8730 2115 8730 2115 8520 2340 8520 2340 8730 +2 4 0 1 20 20 30 -1 30 0.000 0 0 7 0 0 5 + 2340 9090 2100 9090 2100 8880 2340 8880 2340 9090 +2 1 0 5 12 12 45 -1 -1 0.000 0 0 -1 0 0 2 + 5639 2297 11176 5494 +2 1 0 5 23 1 45 -1 -1 0.000 0 0 -1 0 0 2 + 4837 6516 8033 8374 +4 0 0 35 -1 6 14 5.7596 4 180 450 5572 5945 iVM\001 +4 0 0 35 -1 6 14 5.7596 4 180 450 6397 6485 iVM\001 +4 0 0 35 -1 6 14 5.7596 4 180 450 7552 7115 iVM\001 +4 0 0 40 -1 6 18 0.5236 4 225 1815 10665 6615 Virtual Plane\001 +4 0 0 40 -1 6 18 0.5236 4 285 2295 8280 9405 Inception Plane\001 +4 0 0 30 -1 4 14 0.0000 4 225 3330 2430 8325 Inception management VMs\001 +4 0 0 30 -1 4 14 0.0000 4 225 3375 2430 8685 Inception created cloud VMs\001 +4 0 0 30 -1 4 14 0.0000 4 225 4170 2430 9045 Other VMs sharing the same project \001 +4 0 0 30 -1 4 14 0.0000 4 180 3135 2520 9315 in the 'real' OS environment\001 +4 0 0 35 -1 7 16 5.7596 4 195 390 8775 4995 Wk\001 +4 0 0 35 -1 7 16 5.7596 4 195 435 5760 3195 Gw\001 +4 0 0 35 -1 7 16 5.7596 4 195 285 6750 3825 Ct\001 +4 0 0 35 -1 7 16 5.7596 4 195 375 7785 4365 Ch\001 diff --git a/doc/source/ic_user/makefile b/doc/source/ic_user/makefile new file mode 100644 index 0000000..16f9983 --- /dev/null +++ b/doc/source/ic_user/makefile @@ -0,0 +1,32 @@ +# +# Abstract: makes all pdf files. make promote will copy the final .pdf files to the top level source +# make clean cleans up tex detritus, make nuke scrubs everything away. +# Date: 26 August 2013 +# Requires: TeX 3.1415926 (TeX Live 2013), fig2dev +# Mods: +# + +include ../global.make # meta stuff + +fig_list = inception_final start_overview inception_planes +sec_list = overview prep running using examples + + +build_list = ic_user.pdf +all:: $(build_list) + +promote:: $(build_list) + for f in $(build_list);\ + do\ + cp $$f ../;\ + done + +ic_user.pdf:: ic_user.tex $(sec_list:%=%.tex) $(fig_list:%=%.eps) + +# everything except final doc files +clean: + rm -f *converted-to.pdf *.eps *.aux *.log || true + +# everything except the source +nuke: + rm -f $(build_list) *converted-to.pdf *.eps *.aux *.log || true diff --git a/doc/source/ic_user/overview.tex b/doc/source/ic_user/overview.tex new file mode 100644 index 0000000..c9ff101 --- /dev/null +++ b/doc/source/ic_user/overview.tex @@ -0,0 +1,36 @@ +\section{Overview} +Creating an inception cloud consists of preparing your workstation, preparing the VM environment by adding a temporary boot-up machine, +and then executing the \verb!orchestrator! programme to build the cloud. +Once the inception cloud has been created, there is a small amount of housekeeping that is necessary to be able to reach the new cloud. +This document describes the software necessary to support and manage an inception cloud, lists the steps needed to start an +inception cloud, provides information on accessing the inception cloud and includes the command needed to stop the cloud. +The final section contains a small bit of guidance which addresses how to access VMs running on the inception cloud. + +Some knowledge of OpenStack, virtual machines and the Nova client command line interface is assumed. +This document provides some OpenStack commands to assist with VM setup, but makes no attempt to explain +their syntax or to further illustrate any command line parameters that are not directly used in the examples. + +\subsection{Workstation Requirements } +Typically, an inception cloud is started and managed from a regular user account on a remote workstation. +There are several software requirements that are necessary for the workstation, and the user must have slightly +advanced privledges (sudo). +The following list the workstation and user requirements: + +\begin{itemize} +\item User must have \verb!sudo! privileges that allow /etc/hosts and iptables to be modified +\item Python version 2.7 +\item IPython version 0.13.2 or later +\item Sshuttle +\item Nova Client version 2.13.0 or later +\item Nova oslo.config version 1.1.1 or later +\item Git +\item Inception software from github +\end{itemize} + +\noindent +It is possible to use the boot-up VM, described later, as the workstation instead of using it just as a passthrough machine. +With the exception of when sshuttle is needed, the setup and startup of an inception cloud is nearly the +same regardless of whether the "workstation" is real or virtual. +This document will address just the use of a physical workstation, +outside of the OpenStack virtual world, to create and manage an inception cloud; the reader is left to make the +small extrapolations that allow the boot-up VM to be used in place of a real workstation if that is desired. diff --git a/doc/source/ic_user/prep.tex b/doc/source/ic_user/prep.tex new file mode 100644 index 0000000..f91804c --- /dev/null +++ b/doc/source/ic_user/prep.tex @@ -0,0 +1,153 @@ +\section{Preparation} +To prepare the workstation and the virtual environment to start an inception cloud, the tasks listed below, and +explained in more detail in subsequent sections, must first be performed. +All of these should be done on the workstation or from the workstation browser via the OpenStack dashboard or the +Nova client CLI. + +\begin{enumerate} +\item Install software +\item Set environment variables +\item Create keys +\item Start small boot-up VM +\item Add floating IP to the VM +\item Start \verb!sshuttle! +\end{enumerate} + +\subsubsection{Install Software} +Some or all of the required software might already be installed. +Verify that the correct versions of each of the software packages are available on the workstation +and take steps to upgrade or load the missing packages as is needed. +The flavour of Linux installed on your workstation will dictate the exact commands (e.g. apt-get or zypper) +that are needed to load and\/or upgrade Python, sshuttle, and pip. +Pip can then be used to install Nova and Oslo. +Examples of each of the commands that might be needed to manage the required software packages are presented +in Appendix A. + +\subsubsection{Inception source} +The source for inception is available from github. +The command below will fetch the inception source and place it in a directory under the current working directory. + +\small\begin{verbatim} + git clone https://github.com/stackforge/inception.git +\end{verbatim}\normalsize + +Following the execution of the \verb!git! command, switch to the inception directory and verify that the +directory was populated. +Inception may be installed, or used from this directory. +If the decision is made to install inception, the following command should be used: + +\small\begin{verbatim} + python setup.py install +\end{verbatim}\normalsize + +\subsubsection{Set Environment Variables} +Ensure that the environment variables which define the authorisation URL and credentials for OpenStack are set and exported. +OpenStack credentials can be obtained using the OpenStack dashboard interface and following these steps: +\label{set_env_sect} +% +\begin{enumerate} +\item Log into the dashboard +\item Click the \verb!Settings! link (top right) +\item Click the \verb!OpenStack API! link on the left +\item Click the \verb!Download RC File! button and save the file to disk. +\end{enumerate} +%&uindent +% +Once the file has been saved to disk you can source the file (the assumption is made that the +shell being used is bash compatible). +Sourcing the file should prompt for a password, and then export the following variables to the environment: + + +\dlbeg{1.2in} +\dlitem{OS\_AUTH\_URL}{ The reference to a process which provides user authentication.} + +\dlitem{OS\_PASSWORD}{ The password for your account (you'll be prompted to enter this when the file is sourced).} + +\dlitem{OS\_TENANT\_ID}{ The ID string for the tenant (currently refered to as the project on the dashboard).} + +\dlitem{OS\_TENANT\_NAME}{ The human form of the tenant ID.} + +\dlitem{OS\_USERNAME}{ Your user name.} +\dlend + +\subsubsection{Create Keys} +Create (if needed) a public/private key pair and register it with OpenStack. If you do not have a key pair, generate one using +nova. (I prefer to name these with the OpenStack cluster/environment name, and then the key name with an extension that +indicates private key: agave.scooter.pk.) + +\small\begin{verbatim} + touch agave.scooter.pk + chmod 600 agave.scooter.pk + nova keypair-add scooter >>agave.scooter.pk +\end{verbatim}\normalsize + +The commands above will create the key, write it to disk and register the public key with OpenStack. +Executing the \verb!touch! and \verb!chmod! commands prior to generating the key adds a bit of security which prevents the exposure of the key +which results if the permissions on the key file are changed after it is generated. +Regardless of when the permissions are changed, they will need to be changed in order for the file to recognised and used by ssh. + +If you already have a private key (one that several users might share) then a public key can be generated from the private key and registered with OpenStack: + +\small\begin{verbatim} + ssh-keygen -f agave.shared.pk -y >agave.shared.puk + nova keypair-add --pub-key agave.shared.puk shared + +\end{verbatim}\normalsize + +If you have both a public and private key file, then the \verb!ssh-keygen! command can be skipped; it is only necessary to supply the existing public key to +OpenStack using the nova command line. + +\subsubsection{Start Tiny Boot-up VM} +Create and initialise a tiny VM that will act as the initial gateway to the virtual environment for processes running on the workstation. +For the examples used in the remainder of this document, the boot-up VM is given the name \verb!scooter_bv.! +The VM should be started with the key that was registered with OpenStack. + +\small\begin{verbatim} + nova boot --image centos --flavor m1.tiny --key_name shared \ + --security_groups default scooter_bv +} +\end{verbatim}\normalsize + +\noindent +The VM should boot quickly and once it is active you may continue. + +\subsubsection{Add A Floating IP Address} +Add a floating (public) IP address to the new VM so that it can be reached from the "real world." +(xxx.xxx.xxx.xxx is one of the public floating IP addresses that are available; use \verb!nova floating-ip-list! +to get a list of available addresses. + +\small\begin{verbatim} + nova add-floating-ip scooter_bv xxx.xxx.xxx.xxx +\end{verbatim}\normalsize + +\subsubsection{Start sshuttle} +The sshuttle programme creates a tunnel through ssh allowing programmes on the workstation to access VMs created on the +same internal network as the boot-up VM without having to assign each VM a public address. +The sshuttle command is given the private key portion of the key pair that was used to start the boot-up VM; this is +necessary to allow sshuttle to start an ssh session through which the tunnel is created. +The user name (ubuntu in the example below) is any user on the boot-up VM that is available and allows access via +the key (the assumption is that OpenStack created this user, or it was a part of the saved imagee, and the public key was +inserted into the \verb!authorized_keys! file in the user's \verb!.ssh! directory.) + +\small\begin{verbatim} + sshuttle -e ssh -A -i ~/.vmkeys/agave.shared.pk -v \ + -r ubuntu@xxx.xxx.xxx.xxx 192.168.254.0/24 +\end{verbatim}\normalsize + +\noindent +The \verb!-v! option causes sshuttle to be more verbose with messages to the standard error device. +Ultimately, redirecting the output of sshuttle to \verb!/dev/null! and running the process asynchronously, is probably +wise, but initially seeing the verbose messages scroll by in the window is a nice confirmation that the tunnel is active and data +is being transferred. +The \verb!xxx! IP address is the public floating IP address assigned earlier. The second address (192.168.254.0 in the example) +bb the virtual network that is created by OpenStack. +If it is not known, the following command (with suitable path for the public key) might provide the address: + +\small\begin{verbatim} + ssh -i ~/.vmkeys/agave.shared.pk ubuntu@xxx.xxx.xxx.xxx ifconfig eth0 +\end{verbatim}\normalsize + +The netmask can be used to determine the number of bits of the address that are treated as the network ID (probably 24) and thus +added after the slant on the sshuttle command. + +\vspace{20 pt} diff --git a/doc/source/ic_user/running.tex b/doc/source/ic_user/running.tex new file mode 100644 index 0000000..56094ed --- /dev/null +++ b/doc/source/ic_user/running.tex @@ -0,0 +1,189 @@ +\section{Running Orchestrator} +The \verb!orchestrator! command, located in the bin directory under the source that was fetched from github, +is used to start and stop an inception cloud. +The inception cloud environment consists of at least 4 Inception Control VMs (ICVMs) in the environment: + +%&indent +\begin{itemize} +\item A gateway machine that will be given a public IP address and function much in the same way as the +boot-up VM being used to start the cloud. + +\item A controller machine used to run the OpenStack software and to provide the OpenStack Dashboard interface. + +\item A chef machine used to manage Chef installation and configuration scripts. + +\item One or more worker machines used to host the inception virtual machines (iVMs). +\end{itemize} + +\noindent +The following sections describe how orchestrator is used. + +\begin{figure} + \centering + \includegraphics[width=\linewidth]{start_overview.eps} + \tiny + \caption{\small The environment, after orchestrator has created ICVMs, showing the communication path between orchestrator and the ICVMs. + \label{fg_overview} \normalsize + } + \normalsize +\end{figure} + +\subsection{Starting The Inception Cloud} +The \verb!orchestrator! command is located in the \verb!bin! directory within the source cloned from github. +The bin directory can be added to the path, or the command can be executed with a fully qualified path. +It will probably be necessary to add the top level inception directory to the \verb!PYTHONPATH! environment variable +if inception was not installed. +%.sp +Using the \verb!--help! option will cause all of the possible command line options to be written to the tty device. +For the most part, at least for the first time user, only a few are needed and are described below. + +\dlbeg{0.85in} +\dlitem{-p prefix}{ + This command line flag is required and supplies the prefix string that is used when defining the ICVM names. +} + +\vspace{5pt} +\dlitem{-n n}{ + Specifies the number of work ICVMs that are created. The iVMs which are created in the inception cloud are hosted + on the work VMs thus the number needed is directly related to the number of iVMs that will be created in the inception cloud. +} + +\vspace{5pt} +\dlitem{-~-image=}{ + Supplied the image name to be used for all ICVMs. If not supplied a base image of Ubuntu 12.04 (64 bit) is + created and used for each ICVM. +} + +\vspace{5pt} +\dlitem{-~-ssh\_keyfile=}{ + Provides the name of the private key that is to be injected as the user key for each of the + control VMs that are created. +} + +\vspace{5pt} +\dlitem{-~-user=}{ + The user name created on each node with sudo capabilities. If not given, ubuntu is used. +} +\dlend + +\noindent +The following illustrates the command to start an inception cloud with one worker and a prefix of \verb!scooter0.! + +\small\begin{verbatim} + orchestrator -n 1 -p scooter0 \ + --ssh_keyfile=$HOME/.vmkeys/agave.shared.pk +\end{verbatim}\normalsize +\noindent +The creation and initialisation of the ICVMs takes about 20 minutes during which time a fair few messages +are written to standard error. +When orchestrator has finished, a set of messages should be written to stdout indicating success and which give the IP +addresses and URLs for various things in the newly created environment. +The following is a sample of these messages (date, time, and system indentification information has bee excluded for brevity): + +\small\begin{verbatim} + Your inception cloud 'scooter0' is ready!!! + Gateway IP is 135.207.223.158 + Chef server WebUI is http://192.168.254.28:4040 + OpenStack dashboard is https://192.168.254.29 +\end{verbatim}\normalsize + +\subsection{Stopping The Inception Cloud} +The inception cloud can be stopped manually by halting all of the ICVMs, or orchestrator can be used +giving it the \verb!--cleanup! command line flag which causes it to terminate all of the ICVMs. + +\small\begin{verbatim} + orchestrator -p scooter0 --cleanup +\end{verbatim}\normalsize + +\subsection{Finalisation} +It will take approximately 20 minutes for orchestrator to start the inception cloud. +Once orchestrator reports that the inception cloud is ready, a small amount of housekeeping should be done. +These tasks include: + +\begin{itemize} +\item Determining the network addresses of the gateway ICVM. + +\item Repointing sshuttle to use the gateway ICVM and to reference the ICVM control network + +\item Stopping the boot-up VM + +\item Adding the controller to /etc/hosts + +\item Creating credentials for your inception cloud +\end{itemize} + +\subsubsection{Repointing Sshuttle} +Once the ICVMs are running, sshuttle should be "pointed" at the gateway ICVM so that the boot-up VM can be stopped. +Sshuttle must also be set to tunnel requests for the private control network that is used by the +ICVMs as this is the network on which the nova authorisation and dashboard processes listen on. +The following commands illustrate how this can be done: + +\small\begin{verbatim} + nova list | grep scooter0-gateway + ssh ubuntu@yyy.yyy.yyy.yyy ifconfig eth1 + sshuttle -e ssh -A -i ~/.vmkeys/agave.shared.pk -v \ + -r ubuntu@yyy.yyy.yyy.yyy \ + 192.168.254.0/24 zzz.zzz.zzz.0/24 + +\end{verbatim}\normalsize +\noindent +Where: + +\dlbeg{0.9in} +\dlitem{scooter0}{ Is the prefix that was given to orchestrator when the inception cloud was started.} + +\vspace{5pt} +\dlitem{yyy.yyy.yyy.yyy}{ Is the public IP address for the gateway.} + +\vspace{5pt} +\dlitem{zzz.zzz.zzz.0} { + Is the network address of the control network. The netmask also must be checked to determine if /24 is + the appropriate number of bits being used to represent a host id; if not it must be changed to match the netmask. +} + +\vspace{5pt} +\dlitem{ubuntu}{ Is the user name that was injected onto each of the ICVMs. } +\dlend + +After these commands are executed sshuttle will again be running on the workstation and managing a tunnel between the +workstation and both the virtual network and the inception cloud's private control network in the OpenStack environment. + +\subsubsection{Modifying /etc/hosts} +In order to use the inception cloud OpenStack dashboard (URL given in the last set of messages generated by orchestrator), +the workstation must be able to resolve the +controller host name (e.g. \verb!scooter0-controller! using the earlier example prefix). +The easiest way to do this is to have sshuttle forward all DNS requests to the inception cloud environment for resolution. +This is done with the addition of a command line flag on the sshuttle command, however shuffling all of the workstation's DNS +traffic into the VM environment is probably not a very wise choice. +Instead, the host name of the controller, and it's control network IP address (zzz.zzz.zzz.hhh) should be added to the +\verb!/etc/hosts! file on the workstation. + + +\subsubsection{Setting Credentials} +Credentials must be set in the environment to allow nova to be used on the workstation to control the iVMs in the +inception cloud. +The following is a list of variables that must be exported and their approximate values (the IP address supplied for the +authorisation URL will be different as might the username). +The password was given to the user \emph{demo} via the dashboard using the \emph{admin} user ID. + +\small\begin{verbatim} + export OS_AUTH_URL=http://10.251.0.3:5000/v2.0/ + export OS_TENANT_NAME="demo" + export OS_USERNAME=demo + export OS_PASSWORD=demo +\end{verbatim}\normalsize + +The network address given is that of the private control network. +The dashboard can be used to setup any users and\/or projects (tenants) that are needed in the inception cloud. +The admin user ID and password are admin/admin by default. + +\begin{figure} + \centering + \includegraphics[width=\linewidth]{inception_final.eps} + \caption{ + \small The virtual environment after cleanup showing path of browser traffic with the dashboard. + \label{fg_final}\normalsize + } + \normalsize +\end{figure} +Following housekeeping, the environment should be as shown in figure \ref{fg_final}. diff --git a/doc/source/ic_user/start_overview.fig b/doc/source/ic_user/start_overview.fig new file mode 100644 index 0000000..29ce8b9 --- /dev/null +++ b/doc/source/ic_user/start_overview.fig @@ -0,0 +1,102 @@ +#FIG 3.2 Produced by xfig version 3.2.5b +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +1 4 0 1 0 7 45 -1 20 0.000 1 0.0000 6435 2835 142 142 6293 2835 6577 2835 +2 2 0 1 0 6 50 -1 31 0.000 0 0 -1 0 0 5 + 3510 1710 2160 1710 2160 2610 3510 2610 3510 1710 +2 1 0 1 0 7 45 -1 -1 0.000 0 0 -1 1 1 4 + 2 1 1.00 60.00 120.00 + 2 1 1.00 60.00 120.00 + 3510 2250 4950 2250 4770 2430 6660 2430 +2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5 + 3600 4050 3600 450 450 450 450 4050 3600 4050 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 7020 3690 6480 3690 6480 3240 7020 3240 7020 3690 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 7740 3690 7200 3690 7200 3240 7740 3240 7740 3690 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 8460 3690 7920 3690 7920 3240 8460 3240 8460 3690 +2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5 + 9180 3690 8640 3690 8640 3240 9180 3240 9180 3690 +2 4 0 1 0 28 50 -1 30 0.000 0 0 7 0 0 5 + 7470 2520 6480 2520 6480 1980 7470 1980 7470 2520 +2 2 0 1 0 20 50 -1 31 0.000 0 0 -1 0 0 5 + 2070 990 720 990 720 1890 2070 1890 2070 990 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 450 5130 4140 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6840 2520 6840 2880 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6750 2880 6750 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 7470 2880 7470 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8190 2880 8190 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8910 2880 8910 3240 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 1260 6480 1260 +2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5 + 7470 1530 6480 1530 6480 990 7470 990 7470 1530 +2 4 0 1 0 17 59 -1 30 0.000 0 0 7 0 0 5 + 9000 1350 8010 1350 8010 810 9000 810 9000 1350 +2 4 0 1 0 17 58 -1 30 0.000 0 0 7 0 0 5 + 8820 1440 7830 1440 7830 900 8820 900 8820 1440 +2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5 + 8640 1530 7650 1530 7650 990 8640 990 8640 1530 +2 1 1 1 0 7 45 -1 -1 6.000 0 0 -1 0 0 2 + 6120 1710 9900 1710 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6570 3960 9090 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6750 3690 6750 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 7470 3690 7470 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8190 3690 8190 3960 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8910 3690 8910 3960 +2 4 0 1 0 22 50 -1 30 0.000 0 0 7 0 0 5 + 8730 2520 7740 2520 7740 1980 8730 1980 8730 2520 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 8100 2520 8100 2880 +2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5 + 9900 4320 9900 450 6120 450 6120 4320 9900 4320 +2 2 3 2 31 31 54 -1 35 1.500 0 0 -1 0 0 5 + 6390 3060 9630 3060 9630 4230 6390 4230 6390 3060 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 6570 2880 9090 2880 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 2880 6300 2880 +2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2 + 5130 2160 6480 2160 +3 2 1 1 0 7 45 -1 -1 4.000 0 1 0 6 + 2 1 1.00 60.00 120.00 + 2070 1260 2520 1440 3330 1980 5400 1800 7020 2340 6840 3330 + 0.000 -1.000 -1.000 -1.000 -1.000 0.000 +4 0 0 50 -1 4 12 0.0000 4 150 1125 630 720 Workstation\001 +4 0 0 50 -1 4 12 0.0000 4 180 2295 6390 720 OpenStack Environment\001 +4 0 0 45 -1 4 12 0.0000 4 150 825 6570 2250 Boot-VM\001 +4 0 0 45 -1 4 12 0.0000 4 150 330 6570 3600 Gw\001 +4 0 0 45 -1 4 12 0.0000 4 150 225 7290 3600 Ct\001 +4 0 0 45 -1 4 12 0.0000 4 150 285 8010 3600 Ch\001 +4 0 0 45 -1 4 12 0.0000 4 150 300 8730 3600 Wk\001 +4 0 0 45 -1 4 12 0.0000 4 150 1170 810 1530 Orchestrator\001 +4 0 0 45 -1 4 12 0.0000 4 150 675 2520 2250 sshuttle\001 +4 0 0 45 -1 4 10 1.5708 4 120 1185 5040 4140 Public Network\001 +4 0 0 45 -1 4 10 0.0000 4 120 765 6570 1260 Controller\001 +4 0 0 45 -1 4 10 0.0000 4 150 765 7740 1260 Compute\001 +4 0 0 45 -1 4 10 0.0000 4 120 330 8010 2430 VMs\001 +4 0 0 45 -1 4 10 0.0000 4 120 510 7920 2160 Other \001 +4 0 0 45 -1 4 10 0.0000 4 120 1215 8190 2790 Virtual Network\001 +4 0 0 45 -1 4 10 0.0000 4 135 1980 6930 4140 Private (control) Network\001 +4 0 0 45 -1 4 10 0.0000 4 120 360 9360 1620 Real\001 +4 0 0 45 -1 4 10 0.0000 4 120 510 9270 1890 Virtual\001 +4 0 0 45 -1 4 10 1.5708 4 150 750 9360 4050 Inception\001 +4 0 0 45 -1 4 10 1.5708 4 120 495 9540 3960 Cloud\001 diff --git a/doc/source/ic_user/texmf.cnf b/doc/source/ic_user/texmf.cnf new file mode 100644 index 0000000..e947e26 --- /dev/null +++ b/doc/source/ic_user/texmf.cnf @@ -0,0 +1,3 @@ + +openout_any = a +openin_any = a diff --git a/doc/source/ic_user/using.tex b/doc/source/ic_user/using.tex new file mode 100644 index 0000000..c1d452f --- /dev/null +++ b/doc/source/ic_user/using.tex @@ -0,0 +1,55 @@ +\section{Starting and Using iVMs} +The dashboard and\/or nova command line commands can be used to start and manage iVMs within the inception environment. +The iVMs are allocated across the worker ICVM(s) that were created by orchestrator. +The nova command line interface can be used on either the controller ICVM (Ct in the illustration), or directly from +the workstation (provided that the proper environment variables have been defined and that sshuttle is tunneling traffic +to the private control network). +Figure \ref{fg_planes} illustrates the logical relationship of the inception \emph{plane} with the hosting +OpenStack (virtual plane) environment. + + +\begin{figure}[!ht] + \centering + \includegraphics[width=\linewidth]{inception_planes.eps} + \tiny + \caption{\small The relationship between the inception plane and the virtual plane. + \label{fg_planes}\normalsize + } + \normalsize +\end{figure} + +There are two methods which can be used to ssh into an iVM host. +First is to \verb!ssh! into the gateway, then to \verb!ssh! to a worker ICVM, and finally to \verb!ssh! to the desired iVM. +The second is to \emph{string} all of the ssh commands together into a single command. +Regardless of which method is used, the \verb!-A! and \verb!-i! command line options will need to be given on the initial +ssh command in order to forward authorisation with each step, and to use the private key that is associated with the ICVMs. +While it is necessary to use the \verb!-i! option only on the first command, the \verb!-A! option must be given on all of the +ssh commands. + +If a single command line is used, it will also be necessary to use the \verb!-t! option to force ssh to treat each \emph{hop} as +a terminal session. +The next command example illustrates a single ssh command that creates a log-in session on an iVM. + +% this is silly -- latex has no conditional 'eject' and so we must wrap in a tabular to ensure it does not split +% if there isn't room for the whole three lines on the current page/column. +\small\begin{tabular}{p{\textwidth}}\begin{verbatim} + ssh -t -A -i agave.shared.pk ubuntu@135.207.223.158 \ + ssh -t -A ubuntu@scooter0-worker1 \ + ssh -t ubuntu@10.252.0.2 +\end{verbatim} +\end{tabular} +\normalsize + + +If this command is going to be executed from a script, or just to make life easier, it might be good to add the following options +to each of the ssh commands. + +\small\begin{verbatim} + -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no +\end{verbatim}\normalsize + +These prevent information about the hosts being accessed from being saved in the \verb!known_hosts! file and prevent ssh from +complaining if the host information was previously saved and is different from the current information. +Be aware that because the host information is being pushed to \verb!/dev/null,! ssh will indicate that it has been added +each time the commands are executed (this is less bothersome than having to clean out the known hosts file as the +VM host information changes). diff --git a/doc/source/macros/README b/doc/source/macros/README new file mode 100644 index 0000000..5175bea --- /dev/null +++ b/doc/source/macros/README @@ -0,0 +1,2 @@ +These files contain 'macros' that are used by the various doc source. +They aren't complete latex packages, but probably could be. diff --git a/doc/source/macros/deflist.tex b/doc/source/macros/deflist.tex new file mode 100644 index 0000000..aaa9d54 --- /dev/null +++ b/doc/source/macros/deflist.tex @@ -0,0 +1,22 @@ +% ----------------------------------------------------------------------------- +% definition lists: +% better definition list than the tex default, somewhat +% autosized like those in {X}fm, consistently indented text, and it +% _does_ span pages unlike a single tabular. Leave a blank line +% after a \dlitem{} command for a nice amount of space betwen, +% or add a space with a following \vpace{len} command to add more. +% \dlitemcw formats the term using a constant width font, othewise it +% is identical to \dlitem. +% usage: +% \dlbeg{term-width} +% \dlitem{term}{definition text} +% : +% : +% \dlend +% ----------------------------------------------------------------------------- +% +\newlength{\DLdw} +\newcommand{\dlbeg}[1]{\def\DLtw{#1}\setlength{\DLdw}{\textwidth}\addtolength{\DLdw}{-#1}\addtolength{\DLdw}{-0.4in}\vspace{10pt}} +\newcommand{\dlitem}[2]{\noindent\begin{tabular}{p{\DLtw} p{\DLdw}}\sf{#1}\end{tabular}\\} +\newcommand{\dlitemcw}[2]{\begin{tabular}{ p{\DLtw} p{\DLdw} } \tt{#1} & #2 \end{tabular}\\[5pt] } +\newcommand{\dlend}{\vspace{12pt} } diff --git a/doc/source/makefile b/doc/source/makefile new file mode 100644 index 0000000..407bd42 --- /dev/null +++ b/doc/source/makefile @@ -0,0 +1,29 @@ +# simple makefile to build all doc from the subdirectories below and to +# pull the final pdf files to this directory. + +sub_dirs = ic_user + +# buld and prompte the final pdf to this directory +all:: + for d in $(sub_dirs);\ + do\ + echo "build $d";\ + (cd $$d; $(MAKE) && $(MAKE) promote);\ + done + +# scrub everything away execpt source +nuke:: + for d in $(sub_dirs);\ + do\ + echo "build $d";\ + (cd $$d; $(MAKE) nuke );\ + done + rm -f ./*.pdf + +# remove just tex detritis leaving final doc files +clean:: + for d in $(sub_dirs);\ + do\ + echo "build $d";\ + (cd $$d; $(MAKE) nuke );\ + done