Browse Source

Initial push of doc and related files to repo.

Change-Id: I28871653dfe14f219c5fc140fc84a9a01e6fcda7
Scott Daniels 5 years ago
parent
commit
4451cff7bc

+ 6
- 0
doc/source/.gitignore View File

@@ -0,0 +1,6 @@
1
+*.pdf
2
+*.log
3
+*.aux
4
+*.eps
5
+*.sp
6
+*-

+ 17
- 0
doc/source/global.make View File

@@ -0,0 +1,17 @@
1
+# global things needed by all make files -- mostly meta rules
2
+
3
+SHELL = ksh
4
+
5
+# allows the use of ../ in include statements
6
+env = openout_any=a openin_any=a
7
+
8
+%.pdf : %.tex
9
+	$(env) latex -halt-on-error -interaction=nonstopmode -output-format=pdf $<
10
+
11
+%.dvi : %.tex
12
+	$(env) latex -halt-on-error -interaction=nonstopmode -output-format=dvi $<
13
+
14
+# xfig used to produce/maintain figures. this converts to eps
15
+%.eps: %.fig
16
+	fig2dev -L eps <$< >$@
17
+

+ 18
- 0
doc/source/ic_user/examples.tex View File

@@ -0,0 +1,18 @@
1
+\section{Installation examples}
2
+The following commands illustrate how each of the necessary software packages can be installed. 
3
+Your milage may vary depending on wither your system uses \verb!apt-get, zypper,! or some other 
4
+package management software.  
5
+
6
+\small\begin{verbatim}
7
+   apt-get -y install python
8
+   apt-get -y install ipython 
9
+   apt-get -y install pip
10
+   apt-get -y install sshuttle
11
+   pip install python-novaclient
12
+   pip install oslo.config
13
+ 
14
+   cd $HOME/repo               # any writable directory should do
15
+   git clone https://github.com/stackforge/inception.git
16
+   ( cd inception && python setup.py install )
17
+   
18
+\end{verbatim}\normalsize

+ 47
- 0
doc/source/ic_user/ic_user.tex View File

@@ -0,0 +1,47 @@
1
+%% Mnemonic:	ic_user.tex
2
+%% Abstract:	LaTex source for the inception cloud user doc. 
3
+%% Date:		26 August 2013
4
+%% Author:		E. Scott Daniels
5
+%% Mods:		01 Sep 2013  : Converted from {X}fm source
6
+%% ============================================================================================
7
+
8
+\documentclass[letterpaper,8pt]{paper}
9
+%\author{E.~Scott~Daniels}
10
+\title{Inception Cloud User's Guide}
11
+\usepackage{graphicx}
12
+\usepackage{enumitem}
13
+
14
+% must bloody set environment vars to get ../dir/file to work in include.
15
+\input{../macros/deflist}
16
+
17
+
18
+%% ---------- end setup ------------------------
19
+
20
+\begin{document}
21
+\maketitle
22
+
23
+% ----------- main sections --------------------
24
+\input{overview}
25
+\input{prep}
26
+\input{running}
27
+\input{using}
28
+%
29
+% ---------- back sections  ------------------------
30
+%
31
+\newpage
32
+\appendix
33
+\input{examples}
34
+%
35
+% ---------- end matter ------------------------
36
+%
37
+\tiny
38
+\vspace{3in}
39
+\noindent
40
+\rule{\linewidth}{1 pt} 
41
+\dlbeg{0.3in}
42
+\dlitem{Original:}{August 26, 2013}
43
+\dlitem{Revised:}{\today}
44
+\dlitem{Source:}{ic\_user.tex}
45
+\dlend
46
+
47
+\end{document}

+ 100
- 0
doc/source/ic_user/inception_final.fig View File

@@ -0,0 +1,100 @@
1
+#FIG 3.2  Produced by xfig version 3.2.5b
2
+Landscape
3
+Center
4
+Metric
5
+A4      
6
+100.00
7
+Single
8
+-2
9
+1200 2
10
+1 4 0 1 0 7 45 -1 20 0.000 1 0.0000 6435 2835 142 142 6293 2835 6577 2835
11
+2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5
12
+	 3600 4050 3600 450 450 450 450 4050 3600 4050
13
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
14
+	 7020 3690 6480 3690 6480 3240 7020 3240 7020 3690
15
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
16
+	 8460 3690 7920 3690 7920 3240 8460 3240 8460 3690
17
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
18
+	 9180 3690 8640 3690 8640 3240 9180 3240 9180 3690
19
+2 2 0 1 0 15 50 -1 31 0.000 0 0 -1 0 0 5
20
+	 2070 990 720 990 720 1890 2070 1890 2070 990
21
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
22
+	 5130 450 5130 4140
23
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
24
+	 6750 2880 6750 3240
25
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
26
+	 7470 2880 7470 3240
27
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
28
+	 8190 2880 8190 3240
29
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
30
+	 8910 2880 8910 3240
31
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
32
+	 5130 1260 6480 1260
33
+2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5
34
+	 7470 1530 6480 1530 6480 990 7470 990 7470 1530
35
+2 4 0 1 0 17 59 -1 30 0.000 0 0 7 0 0 5
36
+	 9000 1350 8010 1350 8010 810 9000 810 9000 1350
37
+2 4 0 1 0 17 58 -1 30 0.000 0 0 7 0 0 5
38
+	 8820 1440 7830 1440 7830 900 8820 900 8820 1440
39
+2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5
40
+	 8640 1530 7650 1530 7650 990 8640 990 8640 1530
41
+2 1 1 1 0 7 45 -1 -1 6.000 0 0 -1 0 0 2
42
+	 6120 1710 9900 1710
43
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
44
+	 6570 3960 9090 3960
45
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
46
+	 6750 3690 6750 3960
47
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
48
+	 7470 3690 7470 3960
49
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
50
+	 8190 3690 8190 3960
51
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
52
+	 8910 3690 8910 3960
53
+2 4 0 1 0 22 50 -1 30 0.000 0 0 7 0 0 5
54
+	 8730 2520 7740 2520 7740 1980 8730 1980 8730 2520
55
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
56
+	 8100 2520 8100 2880
57
+2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5
58
+	 9900 4320 9900 450 6120 450 6120 4320 9900 4320
59
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
60
+	 5130 2880 6300 2880
61
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
62
+	 5130 3420 6480 3420
63
+2 2 0 1 0 6 50 -1 31 0.000 0 0 -1 0 0 5
64
+	 3330 2790 1980 2790 1980 3690 3330 3690 3330 2790
65
+2 2 3 2 31 31 54 -1 35 1.500 0 0 -1 0 0 5
66
+	 6390 3060 9630 3060 9630 4230 6390 4230 6390 3060
67
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
68
+	 7740 3690 7200 3690 7200 3240 7740 3240 7740 3690
69
+2 1 0 1 0 7 45 -1 -1 0.000 0 0 -1 1 1 4
70
+	2 1 1.00 60.00 120.00
71
+	2 1 1.00 60.00 120.00
72
+	 3325 3172 4765 3172 4585 3352 6475 3352
73
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
74
+	 6570 2880 9090 2880
75
+3 2 1 1 0 7 49 -1 -1 4.000 0 1 1 10
76
+	2 1 1.00 60.00 120.00
77
+	2 1 1.00 60.00 120.00
78
+	 2076 1413 2925 1800 2719 3069 4305 3595 5792 3715 6805 3307
79
+	 6774 3795 7223 3871 7533 3826 7631 3538
80
+	 0.000 -1.000 -1.000 -1.000 -1.000 -1.000 -1.000 -1.000
81
+	 -1.000 0.000
82
+4 0 0 50 -1 4 12 0.0000 4 150 1125 630 720 Workstation\001
83
+4 0 0 50 -1 4 12 0.0000 4 180 2295 6390 720 OpenStack Environment\001
84
+4 0 0 45 -1 4 12 0.0000 4 150 330 6570 3600 Gw\001
85
+4 0 0 45 -1 4 12 0.0000 4 150 225 7290 3600 Ct\001
86
+4 0 0 45 -1 4 12 0.0000 4 150 285 8010 3600 Ch\001
87
+4 0 0 45 -1 4 12 0.0000 4 150 300 8730 3600 Wk\001
88
+4 0 0 45 -1 4 12 0.0000 4 150 735 810 1530 Browser\001
89
+4 0 0 45 -1 4 10 0.0000 4 120 765 6570 1260 Controller\001
90
+4 0 0 45 -1 4 10 0.0000 4 150 765 7740 1260 Compute\001
91
+4 0 0 45 -1 4 10 0.0000 4 120 330 8010 2430 VMs\001
92
+4 0 0 45 -1 4 10 0.0000 4 120 510 7920 2160 Other \001
93
+4 0 0 45 -1 4 10 0.0000 4 120 1215 8190 2790 Virtual Network\001
94
+4 0 0 45 -1 4 10 0.0000 4 135 1980 6930 4140 Private (control) Network\001
95
+4 0 0 45 -1 4 10 0.0000 4 120 360 9360 1620 Real\001
96
+4 0 0 45 -1 4 10 0.0000 4 120 510 9270 1890 Virtual\001
97
+4 0 0 45 -1 4 10 1.5708 4 150 750 9360 4050 Inception\001
98
+4 0 0 45 -1 4 10 1.5708 4 120 495 9540 3960 Cloud\001
99
+4 0 0 45 -1 4 12 0.0000 4 150 675 2430 3240 sshuttle\001
100
+4 0 0 45 -1 4 10 1.5708 4 120 1185 5040 2880 Public Network\001

+ 287
- 0
doc/source/ic_user/inception_planes.fig View File

@@ -0,0 +1,287 @@
1
+#FIG 3.2  Produced by xfig version 3.2.5b
2
+Landscape
3
+Center
4
+Metric
5
+A4      
6
+100.00
7
+Single
8
+-2
9
+1200 2
10
+6 6510 3550 7440 4613
11
+2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6
12
+	 6990 4083 7440 3825 7440 4344 6986 4605 6986 4085 6990 4083
13
+2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5
14
+	 6521 3816 6970 3550 7438 3827 6989 4085 6521 3816
15
+2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6
16
+	 6515 3819 6984 4086 6986 4613 6512 4347 6510 3817 6515 3819
17
+-6
18
+6 7530 4120 8460 5183
19
+2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6
20
+	 8010 4653 8460 4395 8460 4914 8006 5175 8006 4655 8010 4653
21
+2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5
22
+	 7541 4386 7990 4120 8458 4397 8009 4655 7541 4386
23
+2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6
24
+	 7535 4389 8004 4656 8006 5183 7532 4917 7530 4387 7535 4389
25
+-6
26
+6 8535 4720 9465 5783
27
+2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6
28
+	 9015 5253 9465 4995 9465 5514 9011 5775 9011 5255 9015 5253
29
+2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5
30
+	 8546 4986 8995 4720 9463 4997 9014 5255 8546 4986
31
+2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6
32
+	 8540 4989 9009 5256 9011 5783 8537 5517 8535 4987 8540 4989
33
+-6
34
+6 6135 1540 7065 2603
35
+2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6
36
+	 6615 2073 7065 1815 7065 2334 6611 2595 6611 2075 6615 2073
37
+2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6
38
+	 6140 1809 6609 2076 6611 2603 6137 2337 6135 1807 6140 1809
39
+2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5
40
+	 6146 1806 6595 1540 7063 1817 6614 2075 6146 1806
41
+-6
42
+6 5565 2950 6495 4013
43
+2 3 0 1 0 14 42 -1 30 0.000 0 0 -1 0 0 6
44
+	 6045 3483 6495 3225 6495 3744 6041 4005 6041 3485 6045 3483
45
+2 3 0 1 0 14 40 -1 30 0.000 0 0 -1 0 0 5
46
+	 5576 3216 6025 2950 6493 3227 6044 3485 5576 3216
47
+2 3 0 1 0 12 41 -1 30 0.000 0 0 -1 0 0 6
48
+	 5570 3219 6039 3486 6041 4013 5567 3747 5565 3217 5570 3219
49
+-6
50
+6 5309 5688 6239 6751
51
+2 3 0 1 0 17 40 -1 30 0.000 0 0 -1 0 0 5
52
+	 5320 5954 5769 5688 6237 5965 5788 6223 5320 5954
53
+2 3 0 1 0 17 42 -1 30 0.000 0 0 -1 0 0 6
54
+	 5789 6221 6239 5963 6239 6482 5785 6743 5785 6223 5789 6221
55
+2 3 0 1 0 15 41 -1 30 0.000 0 0 -1 0 0 6
56
+	 5314 5957 5783 6224 5785 6751 5311 6485 5309 5955 5314 5957
57
+-6
58
+6 6164 6213 7094 7276
59
+2 3 0 1 0 17 40 -1 30 0.000 0 0 -1 0 0 5
60
+	 6175 6479 6624 6213 7092 6490 6643 6748 6175 6479
61
+2 3 0 1 0 17 42 -1 30 0.000 0 0 -1 0 0 6
62
+	 6644 6746 7094 6488 7094 7007 6640 7268 6640 6748 6644 6746
63
+2 3 0 1 0 15 41 -1 30 0.000 0 0 -1 0 0 6
64
+	 6169 6482 6638 6749 6640 7276 6166 7010 6164 6480 6169 6482
65
+-6
66
+6 7319 6858 8249 7921
67
+2 3 0 1 0 17 40 -1 30 0.000 0 0 -1 0 0 5
68
+	 7330 7124 7779 6858 8247 7135 7798 7393 7330 7124
69
+2 3 0 1 0 17 42 -1 30 0.000 0 0 -1 0 0 6
70
+	 7799 7391 8249 7133 8249 7652 7795 7913 7795 7393 7799 7391
71
+2 3 0 1 0 15 41 -1 30 0.000 0 0 -1 0 0 6
72
+	 7324 7127 7793 7394 7795 7921 7321 7655 7319 7125 7324 7127
73
+-6
74
+6 7124 2078 8054 3141
75
+2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6
76
+	 7604 2611 8054 2353 8054 2872 7600 3133 7600 2613 7604 2611
77
+2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6
78
+	 7129 2347 7598 2614 7600 3141 7126 2875 7124 2345 7129 2347
79
+2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5
80
+	 7135 2344 7584 2078 8052 2355 7603 2613 7135 2344
81
+-6
82
+6 8090 2595 9020 3658
83
+2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6
84
+	 8570 3128 9020 2870 9020 3389 8566 3650 8566 3130 8570 3128
85
+2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6
86
+	 8095 2864 8564 3131 8566 3658 8092 3392 8090 2862 8095 2864
87
+2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5
88
+	 8101 2861 8550 2595 9018 2872 8569 3130 8101 2861
89
+-6
90
+6 9074 3178 10004 4241
91
+2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6
92
+	 9554 3711 10004 3453 10004 3972 9550 4233 9550 3713 9554 3711
93
+2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6
94
+	 9079 3447 9548 3714 9550 4241 9076 3975 9074 3445 9079 3447
95
+2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5
96
+	 9085 3444 9534 3178 10002 3455 9553 3713 9085 3444
97
+-6
98
+6 10074 3811 11004 4874
99
+2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6
100
+	 10554 4344 11004 4086 11004 4605 10550 4866 10550 4346 10554 4344
101
+2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6
102
+	 10079 4080 10548 4347 10550 4874 10076 4608 10074 4078 10079 4080
103
+2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5
104
+	 10085 4077 10534 3811 11002 4088 10553 4346 10085 4077
105
+-6
106
+6 11090 4378 12020 5441
107
+2 3 0 1 0 20 42 -1 30 0.000 0 0 -1 0 0 6
108
+	 11570 4911 12020 4653 12020 5172 11566 5433 11566 4913 11570 4911
109
+2 3 0 1 0 18 41 -1 30 0.000 0 0 -1 0 0 6
110
+	 11095 4647 11564 4914 11566 5441 11092 5175 11090 4645 11095 4647
111
+2 3 0 1 0 20 40 -1 30 0.000 0 0 -1 0 0 5
112
+	 11101 4644 11550 4378 12018 4655 11569 4913 11101 4644
113
+-6
114
+6 3733 5514 10100 9204
115
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
116
+	 3780 6713 8055 9182
117
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
118
+	 8038 9175 10063 8005
119
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
120
+	 5798 5551 10074 8020
121
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
122
+	 3762 6702 5789 5532
123
+-6
124
+6 9958 5472 10867 5859
125
+6 9958 5472 10867 5859
126
+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
127
+1 2 0 1 0 14 35 -1 30 0.000 1 0.0000 10408 5577 450 105 9958 5577 10858 5577
128
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
129
+	 10867 5578 10867 5798
130
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
131
+	 9960 5571 9960 5791
132
+2 2 0 0 14 13 40 -1 30 0.000 0 0 -1 0 0 5
133
+	 9964 5612 10857 5612 10857 5806 9964 5806 9964 5612
134
+-6
135
+6 10310 5496 10519 5649
136
+6 10310 5516 10519 5638
137
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
138
+	 10314 5519 10519 5638
139
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
140
+	 10511 5635 10490 5587
141
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
142
+	 10512 5635 10463 5638
143
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
144
+	 10370 5516 10316 5521
145
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
146
+	 10333 5577 10310 5527
147
+-6
148
+6 10312 5496 10494 5649
149
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
150
+	 10482 5558 10427 5562
151
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
152
+	 10437 5504 10423 5555
153
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
154
+	 10312 5649 10494 5496
155
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
156
+	 10392 5583 10377 5636
157
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
158
+	 10392 5585 10338 5588
159
+-6
160
+-6
161
+-6
162
+6 4629 2917 5538 3304
163
+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
164
+6 4981 2941 5190 3094
165
+6 4981 2961 5190 3083
166
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
167
+	 4985 2964 5190 3083
168
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
169
+	 5182 3080 5161 3032
170
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
171
+	 5183 3080 5134 3083
172
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
173
+	 5041 2961 4987 2966
174
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
175
+	 5004 3022 4981 2972
176
+-6
177
+6 4983 2941 5165 3094
178
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
179
+	 5153 3003 5098 3007
180
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
181
+	 5108 2949 5094 3000
182
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
183
+	 4983 3094 5165 2941
184
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
185
+	 5063 3028 5048 3081
186
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
187
+	 5063 3030 5009 3033
188
+-6
189
+-6
190
+1 2 0 1 0 10 35 -1 30 0.000 1 0.0000 5079 3022 450 105 4629 3022 5529 3022
191
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
192
+	 4631 3016 4631 3236
193
+2 1 0 1 0 12 30 -1 -1 4.000 0 0 -1 0 0 2
194
+	 5538 3023 5538 3243
195
+2 2 0 0 14 9 40 -1 30 0.000 0 0 -1 0 0 5
196
+	 4635 3057 5528 3057 5528 3251 4635 3251 4635 3057
197
+-6
198
+6 405 299 3250 8740
199
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
200
+	 3232 319 3230 7134
201
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
202
+	 439 8690 3235 7075
203
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
204
+	 420 1929 3216 314
205
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
206
+	 429 1910 427 8725
207
+4 0 0 40 -1 6 14 0.5236 4 180 1260 747 2173 Real World\001
208
+-6
209
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
210
+	 3874 3314 9776 6723
211
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
212
+	 6660 1710 12563 5119
213
+2 1 0 5 1 1 45 -1 -1 0.000 0 0 -1 0 0 3
214
+	 5279 3901 8753 5913 8772 5880
215
+2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2
216
+	 6524 4593 6963 4340
217
+2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2
218
+	 5549 4011 5988 3758
219
+2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2
220
+	 7469 5190 7908 4937
221
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
222
+	 9773 6714 12569 5099
223
+2 1 0 5 20 0 45 -1 -1 0.000 0 0 -1 0 0 2
224
+	 2723 7216 2720 793
225
+2 1 0 5 20 12 44 -1 -1 0.000 0 0 -1 0 0 3
226
+	 2743 1845 5861 3645 5889 3597
227
+2 1 0 5 23 12 46 -1 -1 0.000 0 0 -1 0 0 5
228
+	 9150 5500 10012 5979 8638 6765 8641 7993 7998 8379
229
+2 1 0 5 23 12 44 -1 -1 0.000 0 0 -1 0 0 3
230
+	 5246 6763 6058 6295 6056 6253
231
+2 1 0 5 23 12 44 -1 -1 0.000 0 0 -1 0 0 3
232
+	 6195 7257 7007 6789 7005 6747
233
+2 1 0 5 23 12 44 -1 -1 0.000 0 0 -1 0 0 3
234
+	 7302 7913 8114 7445 8112 7403
235
+2 1 0 5 1 12 44 -1 -1 0.000 0 0 -1 0 0 2
236
+	 8537 5811 8976 5558
237
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2
238
+	 7142 3139 7548 2905
239
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3
240
+	 6056 3650 6998 3107 6970 3058
241
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2
242
+	 6163 2586 6569 2352
243
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3
244
+	 9158 5459 10100 4916 10072 4867
245
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2
246
+	 11090 5437 11496 5203
247
+2 1 0 5 23 12 45 -1 -1 0.000 0 0 -1 0 0 2
248
+	 10004 5983 10284 5816
249
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2
250
+	 10460 5665 10968 5371
251
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3
252
+	 8056 4820 8998 4277 8970 4228
253
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2
254
+	 8049 3691 8455 3457
255
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2
256
+	 9052 4281 9458 4047
257
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 2
258
+	 10045 4863 10451 4629
259
+2 1 0 5 12 12 44 -1 -1 0.000 0 0 -1 0 0 3
260
+	 7027 4230 7969 3687 7941 3638
261
+2 1 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
262
+	 3849 3299 6647 1684
263
+2 1 0 5 12 12 45 -1 -1 0.000 0 0 -1 0 0 2
264
+	 5059 3147 6093 2590
265
+2 4 0 1 14 14 30 -1 30 0.000 0 0 7 0 0 5
266
+	 2340 8370 2115 8370 2115 8160 2340 8160 2340 8370
267
+2 4 0 1 17 17 30 -1 30 0.000 0 0 7 0 0 5
268
+	 2340 8730 2115 8730 2115 8520 2340 8520 2340 8730
269
+2 4 0 1 20 20 30 -1 30 0.000 0 0 7 0 0 5
270
+	 2340 9090 2100 9090 2100 8880 2340 8880 2340 9090
271
+2 1 0 5 12 12 45 -1 -1 0.000 0 0 -1 0 0 2
272
+	 5639 2297 11176 5494
273
+2 1 0 5 23 1 45 -1 -1 0.000 0 0 -1 0 0 2
274
+	 4837 6516 8033 8374
275
+4 0 0 35 -1 6 14 5.7596 4 180 450 5572 5945 iVM\001
276
+4 0 0 35 -1 6 14 5.7596 4 180 450 6397 6485 iVM\001
277
+4 0 0 35 -1 6 14 5.7596 4 180 450 7552 7115 iVM\001
278
+4 0 0 40 -1 6 18 0.5236 4 225 1815 10665 6615 Virtual Plane\001
279
+4 0 0 40 -1 6 18 0.5236 4 285 2295 8280 9405 Inception Plane\001
280
+4 0 0 30 -1 4 14 0.0000 4 225 3330 2430 8325 Inception management VMs\001
281
+4 0 0 30 -1 4 14 0.0000 4 225 3375 2430 8685 Inception created cloud VMs\001
282
+4 0 0 30 -1 4 14 0.0000 4 225 4170 2430 9045 Other VMs sharing the same project \001
283
+4 0 0 30 -1 4 14 0.0000 4 180 3135 2520 9315 in the 'real' OS environment\001
284
+4 0 0 35 -1 7 16 5.7596 4 195 390 8775 4995 Wk\001
285
+4 0 0 35 -1 7 16 5.7596 4 195 435 5760 3195 Gw\001
286
+4 0 0 35 -1 7 16 5.7596 4 195 285 6750 3825 Ct\001
287
+4 0 0 35 -1 7 16 5.7596 4 195 375 7785 4365 Ch\001

+ 32
- 0
doc/source/ic_user/makefile View File

@@ -0,0 +1,32 @@
1
+# 
2
+# Abstract:	makes all pdf files. make promote will copy the final .pdf files to the top level source
3
+#			make clean cleans up tex detritus, make nuke scrubs everything away.
4
+# Date: 	26 August 2013
5
+# Requires:	TeX 3.1415926 (TeX Live 2013), fig2dev
6
+# Mods:
7
+#
8
+
9
+include ../global.make	# meta stuff
10
+
11
+fig_list = inception_final start_overview inception_planes
12
+sec_list = overview prep running using examples
13
+
14
+
15
+build_list = ic_user.pdf
16
+all:: $(build_list)
17
+
18
+promote::	$(build_list)
19
+	for f in $(build_list);\
20
+	do\
21
+		cp $$f ../;\
22
+	done
23
+
24
+ic_user.pdf:: ic_user.tex $(sec_list:%=%.tex) $(fig_list:%=%.eps)
25
+
26
+# everything except final doc files
27
+clean:
28
+	rm -f  *converted-to.pdf *.eps *.aux *.log || true
29
+
30
+# everything except the source
31
+nuke:
32
+	rm -f $(build_list) *converted-to.pdf *.eps *.aux *.log || true

+ 36
- 0
doc/source/ic_user/overview.tex View File

@@ -0,0 +1,36 @@
1
+\section{Overview}
2
+Creating an inception cloud consists of preparing your workstation, preparing the VM environment by adding a temporary boot-up machine, 
3
+and then executing the \verb!orchestrator! programme to build the cloud.  
4
+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. 
5
+This document describes the software necessary to support and manage an inception cloud, lists the steps needed to start an 
6
+inception cloud, provides information on accessing the inception cloud and includes the command needed to stop the cloud. 
7
+The final section contains a small bit of guidance which addresses how to access VMs running on the inception cloud.
8
+
9
+Some knowledge of OpenStack, virtual machines and the Nova client command line interface is assumed. 
10
+This document provides some OpenStack commands to assist with VM setup, but makes no attempt to explain 
11
+their syntax or to further illustrate any command line parameters that are not directly used in the examples. 
12
+
13
+\subsection{Workstation Requirements }
14
+Typically, an inception cloud is started and managed from a regular user account on a remote workstation. 
15
+There are several software requirements that are necessary for the workstation, and the user must have slightly 
16
+advanced privledges (sudo).
17
+The following list the workstation and user requirements:
18
+
19
+\begin{itemize}
20
+\item User must have \verb!sudo! privileges that allow /etc/hosts and iptables to be modified
21
+\item Python version 2.7
22
+\item IPython version 0.13.2 or later
23
+\item Sshuttle 
24
+\item Nova Client version 2.13.0 or later
25
+\item Nova oslo.config version 1.1.1 or later
26
+\item Git 
27
+\item Inception software from github
28
+\end{itemize}
29
+
30
+\noindent
31
+It is possible to use the boot-up VM, described later,  as the workstation instead of using it just as a passthrough machine.  
32
+With the exception of when sshuttle is needed, the setup and startup of an inception cloud is nearly the 
33
+same regardless of whether the "workstation" is real or virtual. 
34
+This document will address just the use of a physical workstation, 
35
+outside of the OpenStack virtual world, to create and manage an inception cloud; the reader is left to make the 
36
+small extrapolations that allow the boot-up VM to be used in place of a real workstation if that is desired.

+ 153
- 0
doc/source/ic_user/prep.tex View File

@@ -0,0 +1,153 @@
1
+\section{Preparation}
2
+To prepare the workstation and the virtual environment to start an inception cloud, the tasks listed below, and 
3
+explained in more detail in subsequent sections,  must first be performed. 
4
+All of these should be done on the workstation or from the workstation browser via the OpenStack dashboard or the 
5
+Nova client CLI. 
6
+
7
+\begin{enumerate}
8
+\item Install software
9
+\item Set environment variables
10
+\item Create keys
11
+\item Start small boot-up VM
12
+\item Add floating IP to the VM
13
+\item Start \verb!sshuttle!
14
+\end{enumerate}
15
+
16
+\subsubsection{Install Software}
17
+Some or all of the required software might already be installed. 
18
+Verify that the correct versions of each of the software packages are available on the workstation
19
+and take steps to upgrade or load the missing packages as is needed.  
20
+The flavour of Linux installed on your workstation will dictate the exact commands (e.g. apt-get or zypper)
21
+that are needed to load and\/or upgrade Python, sshuttle, and pip. 
22
+Pip can then be used to install Nova and Oslo. 
23
+Examples of each of the commands that might be needed to manage the required software packages are presented 
24
+in Appendix A. 
25
+
26
+\subsubsection{Inception source}
27
+The source for inception is available from github.
28
+The command below will fetch the inception source and place it in a directory under the current working directory.
29
+
30
+\small\begin{verbatim}
31
+   git clone https://github.com/stackforge/inception.git
32
+\end{verbatim}\normalsize
33
+
34
+Following the execution of the \verb!git! command, switch to the inception directory and verify that the 
35
+directory was populated.  
36
+Inception may be installed, or used from this directory.  
37
+If the decision is made to install inception, the following command should be used:
38
+
39
+\small\begin{verbatim}
40
+   python setup.py install
41
+\end{verbatim}\normalsize
42
+
43
+\subsubsection{Set Environment Variables}
44
+Ensure that the environment variables which define the authorisation URL and credentials for OpenStack are set and exported. 
45
+OpenStack credentials can be obtained using the OpenStack dashboard interface and following these steps:
46
+\label{set_env_sect} 
47
+%
48
+\begin{enumerate}
49
+\item Log into the dashboard
50
+\item Click the \verb!Settings! link (top right)
51
+\item Click the \verb!OpenStack API! link on the left
52
+\item Click the \verb!Download RC File! button and save the file to disk.
53
+\end{enumerate}
54
+%&uindent
55
+%
56
+Once the file has been saved to disk you can source the file (the assumption is made that the 
57
+shell being used is bash compatible).
58
+Sourcing the file should prompt for a password, and then export the following variables to the environment:
59
+
60
+
61
+\dlbeg{1.2in}
62
+\dlitem{OS\_AUTH\_URL}{ The reference to a process which provides user authentication.}
63
+
64
+\dlitem{OS\_PASSWORD}{ The password for your account (you'll be prompted to enter this when the file is sourced).}
65
+
66
+\dlitem{OS\_TENANT\_ID}{ The ID string for the tenant (currently refered to as the project on the dashboard).}
67
+
68
+\dlitem{OS\_TENANT\_NAME}{ The human form of the tenant ID.}
69
+
70
+\dlitem{OS\_USERNAME}{ Your user name.}
71
+\dlend
72
+
73
+\subsubsection{Create Keys}
74
+Create (if needed) a public/private key pair and register it with OpenStack.   If you do not have a key pair, generate one using
75
+nova. (I prefer to name these with the OpenStack cluster/environment name, and then the key name with an extension that 
76
+indicates private key: agave.scooter.pk.) 
77
+
78
+\small\begin{verbatim}
79
+   touch agave.scooter.pk
80
+   chmod 600 agave.scooter.pk
81
+   nova keypair-add scooter >>agave.scooter.pk
82
+\end{verbatim}\normalsize
83
+
84
+The commands above will create the key, write it to disk and register the public key with OpenStack.
85
+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 
86
+which results if the permissions on the key file are changed after it is generated. 
87
+Regardless of when the permissions are changed, they will need to be changed in order for the file to recognised and used by ssh.
88
+
89
+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:
90
+
91
+\small\begin{verbatim}
92
+   ssh-keygen -f agave.shared.pk -y >agave.shared.puk
93
+   nova keypair-add --pub-key agave.shared.puk shared
94
+
95
+\end{verbatim}\normalsize
96
+
97
+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 
98
+OpenStack using the nova command line. 
99
+
100
+\subsubsection{Start Tiny Boot-up VM}
101
+Create and initialise a tiny VM that will act as the initial gateway to the virtual environment for processes running on the workstation.
102
+For the examples used in the remainder of this document, the boot-up VM is given the name \verb!scooter_bv.! 
103
+The VM should be started with the key that was registered with OpenStack. 
104
+
105
+\small\begin{verbatim}
106
+   nova boot --image centos --flavor m1.tiny --key_name shared \
107
+       --security_groups default scooter_bv
108
+}
109
+\end{verbatim}\normalsize
110
+
111
+\noindent
112
+The VM should boot quickly and once it is active you may continue.
113
+
114
+\subsubsection{Add A Floating IP Address}
115
+Add a floating (public) IP address to the new VM so that it can be reached from the "real world."
116
+(xxx.xxx.xxx.xxx is one of the public floating IP addresses that are available; use \verb!nova floating-ip-list! 
117
+to get a list of available addresses.
118
+
119
+\small\begin{verbatim}
120
+   nova  add-floating-ip scooter_bv xxx.xxx.xxx.xxx
121
+\end{verbatim}\normalsize
122
+
123
+\subsubsection{Start sshuttle}
124
+The sshuttle programme creates a tunnel through ssh allowing programmes on the workstation to access VMs created on the 
125
+same internal network as the boot-up VM without having to assign each VM a public address. 
126
+The sshuttle command is given the private key portion of the key pair that was used to start the boot-up VM; this is 
127
+necessary to allow sshuttle to start an ssh session through which the tunnel is created.
128
+The user name (ubuntu in the example below) is any user on the boot-up VM that is available and allows access via
129
+the key (the assumption is that OpenStack created this user, or it was a part of the saved imagee,  and the public key was 
130
+inserted into the \verb!authorized_keys! file in the user's \verb!.ssh! directory.)
131
+
132
+\small\begin{verbatim}
133
+   sshuttle -e ssh -A -i ~/.vmkeys/agave.shared.pk -v \
134
+      -r ubuntu@xxx.xxx.xxx.xxx 192.168.254.0/24 
135
+\end{verbatim}\normalsize
136
+
137
+\noindent
138
+The \verb!-v! option causes sshuttle to be more verbose with messages to the standard error device.
139
+Ultimately, redirecting the output of sshuttle to \verb!/dev/null! and running the process asynchronously, is probably 
140
+wise, but initially seeing the verbose messages scroll by in the window is a nice confirmation that the tunnel is active and data 
141
+is being transferred. 
142
+The \verb!xxx! IP address is the public floating IP address assigned earlier.  The second address (192.168.254.0 in the example)
143
+bb the virtual network that is created by OpenStack.  
144
+If it is not known, the following command (with suitable path for the public key) might provide the address:
145
+
146
+\small\begin{verbatim}
147
+   ssh -i ~/.vmkeys/agave.shared.pk ubuntu@xxx.xxx.xxx.xxx ifconfig eth0
148
+\end{verbatim}\normalsize
149
+
150
+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
151
+added after the slant on the sshuttle command.
152
+
153
+\vspace{20 pt}

+ 189
- 0
doc/source/ic_user/running.tex View File

@@ -0,0 +1,189 @@
1
+\section{Running Orchestrator}
2
+The \verb!orchestrator! command, located in the bin directory under the source that was fetched from github, 
3
+is used to start and stop an inception cloud. 
4
+The inception cloud environment consists of at least 4 Inception Control VMs (ICVMs)  in the environment:
5
+
6
+%&indent
7
+\begin{itemize}
8
+\item A gateway machine that will be given a public IP address and function much in the same way as the 
9
+boot-up VM being used to start the cloud. 
10
+
11
+\item A controller machine used to run the OpenStack software and to provide the OpenStack Dashboard interface. 
12
+
13
+\item A chef machine used to manage Chef installation and configuration scripts. 
14
+
15
+\item One or more worker machines used to host the inception virtual machines (iVMs). 
16
+\end{itemize}
17
+
18
+\noindent
19
+The following sections describe how orchestrator is used. 
20
+
21
+\begin{figure}
22
+  \centering
23
+  \includegraphics[width=\linewidth]{start_overview.eps}
24
+  \tiny
25
+  \caption{\small The environment, after orchestrator has created ICVMs, showing the communication path between orchestrator and the ICVMs.
26
+    \label{fg_overview} \normalsize
27
+  }
28
+  \normalsize
29
+\end{figure}
30
+
31
+\subsection{Starting The Inception Cloud}
32
+The \verb!orchestrator! command is located in the \verb!bin! directory within the source cloned from github. 
33
+The bin directory can be added to the path, or the command can be executed with a fully qualified path.  
34
+It will probably be necessary to add the top level inception directory to the \verb!PYTHONPATH! environment variable
35
+if inception was not installed. 
36
+%.sp
37
+Using the \verb!--help! option will cause all of the possible command line options to be written to the tty device. 
38
+For the most part, at least for the first time user, only a few are needed and are described below. 
39
+
40
+\dlbeg{0.85in}
41
+\dlitem{-p prefix}{ 
42
+	This command line flag is required and supplies the prefix string that is used when defining the ICVM names. 
43
+}
44
+
45
+\vspace{5pt}
46
+\dlitem{-n n}{ 
47
+	Specifies the number of work ICVMs that are created.  The iVMs which are created in the inception cloud are hosted 
48
+	on the work VMs thus the number needed is directly related to the number of iVMs that will be created in the inception cloud. 
49
+}
50
+
51
+\vspace{5pt}
52
+\dlitem{-~-image=}{ 
53
+	Supplied the image name to be used for all ICVMs.  If not supplied a base image of Ubuntu 12.04 (64 bit) is 
54
+	created and used for each ICVM. 
55
+}
56
+
57
+\vspace{5pt}
58
+\dlitem{-~-ssh\_keyfile=}{ 
59
+	Provides the name of the private key that is to be injected as the user key for each of the 
60
+	control VMs that are created.
61
+}
62
+
63
+\vspace{5pt}
64
+\dlitem{-~-user=}{ 
65
+	The user name created on each node with sudo capabilities. If not given, ubuntu is used. 
66
+}
67
+\dlend
68
+
69
+\noindent
70
+The following illustrates the command to start an inception cloud with one worker and a prefix of \verb!scooter0.!
71
+
72
+\small\begin{verbatim}
73
+   orchestrator  -n 1 -p scooter0 \
74
+       --ssh_keyfile=$HOME/.vmkeys/agave.shared.pk
75
+\end{verbatim}\normalsize
76
+\noindent
77
+The creation and initialisation of the ICVMs takes about 20 minutes during which time a fair few messages
78
+are written to standard error. 
79
+When orchestrator has finished, a set of messages should be written to stdout indicating success and which give the IP 
80
+addresses and URLs for various things in the newly created environment.  
81
+The following is a sample of these messages (date, time, and system indentification information has bee excluded for brevity):
82
+
83
+\small\begin{verbatim}
84
+   Your inception cloud 'scooter0' is ready!!!
85
+   Gateway IP is 135.207.223.158
86
+   Chef server WebUI is http://192.168.254.28:4040
87
+   OpenStack dashboard is https://192.168.254.29
88
+\end{verbatim}\normalsize
89
+
90
+\subsection{Stopping The Inception Cloud}
91
+The inception cloud can be stopped manually by halting all of the ICVMs, or orchestrator can be used
92
+giving it the \verb!--cleanup! command line flag which causes it to terminate all of the ICVMs.
93
+
94
+\small\begin{verbatim}
95
+   orchestrator  -p scooter0  --cleanup 
96
+\end{verbatim}\normalsize
97
+
98
+\subsection{Finalisation}
99
+It will take approximately 20 minutes for orchestrator to start the inception cloud.
100
+Once orchestrator reports that the inception cloud is ready, a small amount of housekeeping should be done. 
101
+These tasks include:
102
+
103
+\begin{itemize}
104
+\item Determining the network addresses of the gateway ICVM.
105
+
106
+\item Repointing sshuttle to use the gateway ICVM and to reference the ICVM control network
107
+
108
+\item Stopping the boot-up VM
109
+
110
+\item Adding the controller to /etc/hosts
111
+
112
+\item Creating credentials for your inception cloud
113
+\end{itemize}
114
+
115
+\subsubsection{Repointing Sshuttle}
116
+Once the ICVMs are running, sshuttle should be "pointed" at the gateway ICVM so that the boot-up VM can be stopped. 
117
+Sshuttle must also be set to tunnel requests for the private control network that is used by the 
118
+ICVMs as this is the network on which the nova authorisation and dashboard processes listen on. 
119
+The following commands illustrate how this can be done:  
120
+
121
+\small\begin{verbatim}
122
+   nova list | grep scooter0-gateway          
123
+   ssh ubuntu@yyy.yyy.yyy.yyy ifconfig eth1   
124
+   sshuttle -e ssh -A -i ~/.vmkeys/agave.shared.pk -v \
125
+            -r ubuntu@yyy.yyy.yyy.yyy  \
126
+            192.168.254.0/24 zzz.zzz.zzz.0/24
127
+
128
+\end{verbatim}\normalsize
129
+\noindent
130
+Where:
131
+
132
+\dlbeg{0.9in}
133
+\dlitem{scooter0}{ Is the prefix that was given to orchestrator when the inception cloud was started.}
134
+
135
+\vspace{5pt}
136
+\dlitem{yyy.yyy.yyy.yyy}{ Is the public IP address for the gateway.}
137
+
138
+\vspace{5pt}
139
+\dlitem{zzz.zzz.zzz.0} { 
140
+	Is the network address of the control network. The netmask also must be checked to determine if /24 is 
141
+	the appropriate number of bits being used to represent a host id; if not it must be changed to match the netmask.  
142
+}
143
+
144
+\vspace{5pt}
145
+\dlitem{ubuntu}{ Is the user name that was injected onto each of the ICVMs. }
146
+\dlend
147
+
148
+After these commands are executed sshuttle will again be running on the workstation and managing a tunnel between the 
149
+workstation and both the virtual network and the inception cloud's private control network in the OpenStack environment. 
150
+
151
+\subsubsection{Modifying /etc/hosts}
152
+In order to use the inception cloud OpenStack dashboard (URL given in the last set of messages generated by orchestrator),
153
+the workstation must be able to resolve the 
154
+controller host name (e.g. \verb!scooter0-controller! using the earlier example prefix).  
155
+The easiest way to do this is to have sshuttle forward all DNS requests to the inception cloud environment for resolution. 
156
+This is done with the addition of a command line flag on the sshuttle command, however shuffling all of the workstation's DNS
157
+traffic into the VM environment is probably not a very wise choice. 
158
+Instead, the host name of the controller, and it's control network IP address (zzz.zzz.zzz.hhh) should be added to the 
159
+\verb!/etc/hosts! file on the workstation.   
160
+
161
+
162
+\subsubsection{Setting Credentials}
163
+Credentials must be set in the environment to allow nova to be used on the workstation to control the iVMs in the 
164
+inception cloud.  
165
+The following is a list of variables that must be exported and their approximate values (the IP address supplied for the 
166
+authorisation URL will be different as might the username).  
167
+The password was given to the user \emph{demo} via the dashboard using the \emph{admin} user ID.
168
+
169
+\small\begin{verbatim}
170
+  export OS_AUTH_URL=http://10.251.0.3:5000/v2.0/
171
+  export OS_TENANT_NAME="demo"
172
+  export OS_USERNAME=demo
173
+  export OS_PASSWORD=demo
174
+\end{verbatim}\normalsize
175
+
176
+The network address given is that of the private control network. 
177
+The dashboard can be used to setup any users and\/or projects (tenants) that are needed in the inception cloud. 
178
+The admin user ID and password are admin/admin by default. 
179
+
180
+\begin{figure}
181
+  \centering
182
+  \includegraphics[width=\linewidth]{inception_final.eps}
183
+  \caption{
184
+	\small The virtual environment after cleanup showing path of browser traffic with the dashboard.
185
+  	\label{fg_final}\normalsize
186
+  }
187
+  \normalsize
188
+\end{figure}
189
+Following housekeeping, the environment should be as shown in figure \ref{fg_final}.

+ 102
- 0
doc/source/ic_user/start_overview.fig View File

@@ -0,0 +1,102 @@
1
+#FIG 3.2  Produced by xfig version 3.2.5b
2
+Landscape
3
+Center
4
+Metric
5
+A4      
6
+100.00
7
+Single
8
+-2
9
+1200 2
10
+1 4 0 1 0 7 45 -1 20 0.000 1 0.0000 6435 2835 142 142 6293 2835 6577 2835
11
+2 2 0 1 0 6 50 -1 31 0.000 0 0 -1 0 0 5
12
+	 3510 1710 2160 1710 2160 2610 3510 2610 3510 1710
13
+2 1 0 1 0 7 45 -1 -1 0.000 0 0 -1 1 1 4
14
+	2 1 1.00 60.00 120.00
15
+	2 1 1.00 60.00 120.00
16
+	 3510 2250 4950 2250 4770 2430 6660 2430
17
+2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5
18
+	 3600 4050 3600 450 450 450 450 4050 3600 4050
19
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
20
+	 7020 3690 6480 3690 6480 3240 7020 3240 7020 3690
21
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
22
+	 7740 3690 7200 3690 7200 3240 7740 3240 7740 3690
23
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
24
+	 8460 3690 7920 3690 7920 3240 8460 3240 8460 3690
25
+2 4 0 1 0 14 50 -1 30 0.000 0 0 7 0 0 5
26
+	 9180 3690 8640 3690 8640 3240 9180 3240 9180 3690
27
+2 4 0 1 0 28 50 -1 30 0.000 0 0 7 0 0 5
28
+	 7470 2520 6480 2520 6480 1980 7470 1980 7470 2520
29
+2 2 0 1 0 20 50 -1 31 0.000 0 0 -1 0 0 5
30
+	 2070 990 720 990 720 1890 2070 1890 2070 990
31
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
32
+	 5130 450 5130 4140
33
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
34
+	 6840 2520 6840 2880
35
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
36
+	 6750 2880 6750 3240
37
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
38
+	 7470 2880 7470 3240
39
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
40
+	 8190 2880 8190 3240
41
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
42
+	 8910 2880 8910 3240
43
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
44
+	 5130 1260 6480 1260
45
+2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5
46
+	 7470 1530 6480 1530 6480 990 7470 990 7470 1530
47
+2 4 0 1 0 17 59 -1 30 0.000 0 0 7 0 0 5
48
+	 9000 1350 8010 1350 8010 810 9000 810 9000 1350
49
+2 4 0 1 0 17 58 -1 30 0.000 0 0 7 0 0 5
50
+	 8820 1440 7830 1440 7830 900 8820 900 8820 1440
51
+2 4 0 1 0 17 50 -1 30 0.000 0 0 7 0 0 5
52
+	 8640 1530 7650 1530 7650 990 8640 990 8640 1530
53
+2 1 1 1 0 7 45 -1 -1 6.000 0 0 -1 0 0 2
54
+	 6120 1710 9900 1710
55
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
56
+	 6570 3960 9090 3960
57
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
58
+	 6750 3690 6750 3960
59
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
60
+	 7470 3690 7470 3960
61
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
62
+	 8190 3690 8190 3960
63
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
64
+	 8910 3690 8910 3960
65
+2 4 0 1 0 22 50 -1 30 0.000 0 0 7 0 0 5
66
+	 8730 2520 7740 2520 7740 1980 8730 1980 8730 2520
67
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
68
+	 8100 2520 8100 2880
69
+2 4 0 1 0 7 60 -1 -1 0.000 0 0 7 0 0 5
70
+	 9900 4320 9900 450 6120 450 6120 4320 9900 4320
71
+2 2 3 2 31 31 54 -1 35 1.500 0 0 -1 0 0 5
72
+	 6390 3060 9630 3060 9630 4230 6390 4230 6390 3060
73
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
74
+	 6570 2880 9090 2880
75
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
76
+	 5130 2880 6300 2880
77
+2 1 0 2 0 7 45 -1 -1 0.000 0 0 -1 0 0 2
78
+	 5130 2160 6480 2160
79
+3 2 1 1 0 7 45 -1 -1 4.000 0 1 0 6
80
+	2 1 1.00 60.00 120.00
81
+	 2070 1260 2520 1440 3330 1980 5400 1800 7020 2340 6840 3330
82
+	 0.000 -1.000 -1.000 -1.000 -1.000 0.000
83
+4 0 0 50 -1 4 12 0.0000 4 150 1125 630 720 Workstation\001
84
+4 0 0 50 -1 4 12 0.0000 4 180 2295 6390 720 OpenStack Environment\001
85
+4 0 0 45 -1 4 12 0.0000 4 150 825 6570 2250 Boot-VM\001
86
+4 0 0 45 -1 4 12 0.0000 4 150 330 6570 3600 Gw\001
87
+4 0 0 45 -1 4 12 0.0000 4 150 225 7290 3600 Ct\001
88
+4 0 0 45 -1 4 12 0.0000 4 150 285 8010 3600 Ch\001
89
+4 0 0 45 -1 4 12 0.0000 4 150 300 8730 3600 Wk\001
90
+4 0 0 45 -1 4 12 0.0000 4 150 1170 810 1530 Orchestrator\001
91
+4 0 0 45 -1 4 12 0.0000 4 150 675 2520 2250 sshuttle\001
92
+4 0 0 45 -1 4 10 1.5708 4 120 1185 5040 4140 Public Network\001
93
+4 0 0 45 -1 4 10 0.0000 4 120 765 6570 1260 Controller\001
94
+4 0 0 45 -1 4 10 0.0000 4 150 765 7740 1260 Compute\001
95
+4 0 0 45 -1 4 10 0.0000 4 120 330 8010 2430 VMs\001
96
+4 0 0 45 -1 4 10 0.0000 4 120 510 7920 2160 Other \001
97
+4 0 0 45 -1 4 10 0.0000 4 120 1215 8190 2790 Virtual Network\001
98
+4 0 0 45 -1 4 10 0.0000 4 135 1980 6930 4140 Private (control) Network\001
99
+4 0 0 45 -1 4 10 0.0000 4 120 360 9360 1620 Real\001
100
+4 0 0 45 -1 4 10 0.0000 4 120 510 9270 1890 Virtual\001
101
+4 0 0 45 -1 4 10 1.5708 4 150 750 9360 4050 Inception\001
102
+4 0 0 45 -1 4 10 1.5708 4 120 495 9540 3960 Cloud\001

+ 3
- 0
doc/source/ic_user/texmf.cnf View File

@@ -0,0 +1,3 @@
1
+
2
+openout_any = a
3
+openin_any = a

+ 55
- 0
doc/source/ic_user/using.tex View File

@@ -0,0 +1,55 @@
1
+\section{Starting and Using iVMs}
2
+The dashboard and\/or nova command line commands can be used to start and manage iVMs within the inception environment.  
3
+The iVMs are allocated across the worker ICVM(s) that were created by orchestrator.
4
+The nova command line interface can be used on either the controller ICVM (Ct in the illustration), or directly from 
5
+the workstation (provided that the proper environment variables have been defined and that sshuttle is tunneling traffic
6
+to the private control network).  
7
+Figure \ref{fg_planes} illustrates the logical relationship of the inception \emph{plane} with the hosting 
8
+OpenStack (virtual plane) environment. 
9
+
10
+
11
+\begin{figure}[!ht]
12
+  \centering
13
+  \includegraphics[width=\linewidth]{inception_planes.eps}
14
+  \tiny
15
+  \caption{\small The relationship between the inception plane and the virtual plane.
16
+    \label{fg_planes}\normalsize
17
+  }
18
+  \normalsize
19
+\end{figure}
20
+
21
+There are two methods which can be used to ssh into an iVM host. 
22
+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. 
23
+The second is to \emph{string} all of the ssh commands together into a single command.  
24
+Regardless of which method is used, the \verb!-A! and \verb!-i! command line options will need to be given on the initial
25
+ssh command in order to forward authorisation with each step, and to use the private key that is associated with the ICVMs. 
26
+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
27
+ssh commands.  
28
+
29
+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 
30
+a terminal session.  
31
+The next command example illustrates a single ssh command that creates a log-in session on an iVM.
32
+
33
+% this is silly -- latex has no conditional 'eject' and so we must wrap in a tabular to ensure it does not split
34
+% if there isn't room for the whole three lines on the current page/column. 
35
+\small\begin{tabular}{p{\textwidth}}\begin{verbatim}
36
+   ssh -t -A -i agave.shared.pk ubuntu@135.207.223.158  \
37
+       ssh -t -A ubuntu@scooter0-worker1  \
38
+       ssh -t ubuntu@10.252.0.2
39
+\end{verbatim}
40
+\end{tabular}
41
+\normalsize
42
+
43
+
44
+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
45
+to each of the ssh commands.
46
+
47
+\small\begin{verbatim}
48
+   -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 
49
+\end{verbatim}\normalsize
50
+
51
+These prevent information about the hosts being accessed  from being saved in the \verb!known_hosts! file and prevent ssh from 
52
+complaining if the host information was previously saved and is different from the current information. 
53
+Be aware that because the host information is being pushed to \verb!/dev/null,! ssh will indicate that it has been added 
54
+each time the commands are executed (this is less bothersome than having to clean out the known hosts file as the 
55
+VM host information changes).

+ 2
- 0
doc/source/macros/README View File

@@ -0,0 +1,2 @@
1
+These files contain 'macros' that are used by the various doc source. 
2
+They aren't complete latex packages, but probably could be. 

+ 22
- 0
doc/source/macros/deflist.tex View File

@@ -0,0 +1,22 @@
1
+% -----------------------------------------------------------------------------
2
+% definition lists:
3
+% 	better definition list than the tex default, somewhat
4
+% 	autosized like those in {X}fm, consistently indented text, and it 
5
+% 	_does_ span pages unlike a single tabular. Leave a blank line
6
+% 	after a \dlitem{} command for a nice amount of space betwen, 
7
+% 	or add a space with a following \vpace{len} command to add more. 
8
+%	\dlitemcw formats the term using a constant width font, othewise it 
9
+%	is identical to \dlitem.
10
+% usage:
11
+%	\dlbeg{term-width}
12
+%	\dlitem{term}{definition text}
13
+%	:
14
+%	:
15
+%	\dlend
16
+% -----------------------------------------------------------------------------
17
+%
18
+\newlength{\DLdw}
19
+\newcommand{\dlbeg}[1]{\def\DLtw{#1}\setlength{\DLdw}{\textwidth}\addtolength{\DLdw}{-#1}\addtolength{\DLdw}{-0.4in}\vspace{10pt}}
20
+\newcommand{\dlitem}[2]{\noindent\begin{tabular}{p{\DLtw} p{\DLdw}}\sf{#1}&#2\end{tabular}\\} 
21
+\newcommand{\dlitemcw}[2]{\begin{tabular}{ p{\DLtw} p{\DLdw} } \tt{#1} & #2 \end{tabular}\\[5pt] } 
22
+\newcommand{\dlend}{\vspace{12pt} }

+ 29
- 0
doc/source/makefile View File

@@ -0,0 +1,29 @@
1
+# simple makefile to build all doc from the subdirectories below and to 
2
+# pull the final pdf files to this directory.
3
+
4
+sub_dirs = ic_user
5
+
6
+# buld and prompte the final pdf to this directory
7
+all::
8
+	for d in $(sub_dirs);\
9
+	do\
10
+		echo "build $d";\
11
+		(cd $$d; $(MAKE) && $(MAKE) promote);\
12
+	done
13
+
14
+# scrub everything away execpt source
15
+nuke::
16
+	for d in $(sub_dirs);\
17
+	do\
18
+		echo "build $d";\
19
+		(cd $$d; $(MAKE) nuke );\
20
+	done
21
+	rm -f ./*.pdf
22
+
23
+# remove just tex detritis leaving final doc files
24
+clean::
25
+	for d in $(sub_dirs);\
26
+	do\
27
+		echo "build $d";\
28
+		(cd $$d; $(MAKE) nuke );\
29
+	done

Loading…
Cancel
Save