haas/spring2026/unix/projects/pbx0.md
... ...
@@ -0,0 +1,257 @@
1
+# CSCS1730 UNIX/Linux Fundamentals
2
+
3
+# PROJECT: THE PUZZLEBOX (dac0)
4
+
5
+## OBJECTIVE
6
+
7
+Use your observational skills, ability to track and utilize details,
8
+problem solving abilities, and investigative prowess to unravel the
9
+puzzle box, which will attempt to throw obstructions in your path to
10
+deter you from success.
11
+
12
+## PROCESS
13
+
14
+Do note, the productive way to go about this project involves taking the
15
+following steps:
16
+
17
+ * starting early
18
+ * reading the project page
19
+ * asking questions regarding things you do not know, are not clear on, or are confused about
20
+ * experimenting and exploring the your files, using tools familiar and new to try and unravel the puzzle.
21
+
22
+If you start too late, and do not ask questions, and do not have enough
23
+time and don't know what is going on, you are not doing the project
24
+correctly.
25
+
26
+## TASK
27
+
28
+You are to unravel the puzzle, getting to the instructions inside. Be
29
+wary of deceptions and obstacles trying to throw you off track.
30
+
31
+To start off, there is a starter puzzle, **ascii.512** that must be
32
+solved and acted upon first before you can get to your actual puzzle.
33
+
34
+Once you work through the starter puzzle, you can proceed to your actual
35
+puzzlebox puzzle.
36
+
37
+You are seeking the creation of two files, that you will submit:
38
+
39
+ * **results** - the final instructions correctly unscrambled
40
+ * **pbx0steps** - a list of the steps taken to accomplish the core task
41
+
42
+## NO GRABIT
43
+
44
+As part of this activity is to test your ability to navigate around the
45
+filesystem and manipulate files on your own, there is no grabit
46
+configured for this project.
47
+
48
+Navigate to the UNIX PUBLIC DIRECTORY yourself and manually copy your
49
+project files back into your repository.
50
+
51
+## TOOLBOX
52
+
53
+In addition to tools you may already be familiar with from previous
54
+projects, you may also want to check out:
55
+
56
+ * **ar**(**1**)
57
+ * **basenc**(**1**)
58
+ * **cpio**(**1**)
59
+ * **file**(**1**)
60
+ * **lzma**(**1**)
61
+ * **sort**(**1**)
62
+ * **tr**(**1**)
63
+
64
+You are NOT to make use of, as part of your puzzle solution, any steps
65
+that involve interactive tools (such as **nano**), nor utilize **sed**,
66
+**ed**, or **awk** in your solutions.
67
+
68
+## NOTE
69
+
70
+While you may need to install any needed packages on your pi to perform
71
+tasks related to this project, do keep in mind that for the actual
72
+solving of the puzzlebox:
73
+
74
+ * you do NOT need to call upon sudo / root access in any way (solutions containing such steps will be considered to not be following the spirit of the project)
75
+ * all actionable steps taken are to be done using **non-interactive** tools. There is zero need to make use of an interactive tool like **nano**. Solutions that make central use of interactive tools will be considered to not be following the spirit of the project.
76
+
77
+While you as a user investigating things may end up using various tools
78
+to see what is going on, your resultant steps file is to only be
79
+representative of the core automated/non-interactive task the computer
80
+is performing (with value-added comments giving pertinent clued-in
81
+information as a result of your observations and investigations).
82
+
83
+## BACKGROUND
84
+
85
+The type of a file can be extremely important when determining what
86
+application is used to open it.
87
+
88
+As discussed on a few occasions already, conventional UNIX filesystems do
89
+not have any special treatment for file extensions. It is therefore said
90
+that UNIX ignores them; that means we can use more characters as valid
91
+symbols in filenames.
92
+
93
+On systems that have engrained support for filename extensions (say, a
94
+DOT followed by 3 characters), that actually limits our ability to name
95
+files.
96
+
97
+In UNIX, it is not uncommon to find files named **archive.tar.gz**, and
98
+since UNIX ignores extensions, this is a perfectly legitimate filename...
99
+and it is also quite informative (we are clued in on potential actions
100
+taken on this file, as well as what tools to make use of).
101
+
102
+Most of the time a file is named correctly, for instance a file ending in
103
+**.c** can be assumed to be the source code of a C program, or **.gz** to
104
+be a gzipped file. These are not extensions, they are traditional naming
105
+conventions (just as we tend to call those petrol-powered metal boxes
106
+with 4 rubberized wheels a "car"... we CAN call it something else, but
107
+that may cause bumps in otherwise smooth communications).
108
+
109
+With the **dircolors**(**1**) utility colorizing specific files, it is
110
+further assuming that files which end in **.mpg** are really MPEG files
111
+and colors them accordingly, and the same for **.zip** files, etc.
112
+
113
+In other operating systems, a file's extension determines what
114
+application is used to open the particular file. If a file that ends in
115
+**.mp3** is really a **.png** file, the default MP3 player is going to
116
+have difficulties.
117
+
118
+Sometimes files are not always named properly, either due to a web
119
+browser mangling an extension or for whatever reason. When a file is more
120
+than meets the eye, we must rely on the various tools available to use to
121
+determine what in fact it is.
122
+
123
+## THE FILE UTILITY
124
+
125
+In UNIX there is a nifty little utility called **file** that attempts to
126
+determine the actual type of a file by checking a series of properties.
127
+From the **file**(**1**) man page:
128
+
129
+There are three sets of tests, performed in this order:
130
+
131
+ - filesystem tests,
132
+ - magic number tests,
133
+ - and language tests.
134
+
135
+The first test that succeeds causes the file type to be printed.
136
+
137
+A *filesystem* test checks to see if the file is non-ordinary (such as a
138
+socket, symbolic link, or other special file).
139
+
140
+The *magic number* test is a check of files conforming to existing fixed
141
+formats, typically by examining the file at the binary level. If using a
142
+hex editor, you will find that **.gz** files should always start with the
143
+same sequence of hexadecimal values.
144
+
145
+Finally, if the file is determined to be a simple ASCII file, it will
146
+attempt to analyze whether or not it conforms to some language (ie C
147
+source code vs. an HTML document).
148
+
149
+Note that **file** is not always perfect, but for most cases will get the
150
+job done. Try checking files in your home directory or elsewhere on the
151
+system and see the results. Should file not be able to give you a clear
152
+answer, you must still result to your other skills and mental faculties--
153
+test and debug the situation.
154
+
155
+Refer to the **file**(**1**) manual page or your references for more
156
+information.
157
+
158
+## PROJECT
159
+
160
+For this project, files are located in the **pbx0/** subdirectory of the
161
+**UNIX Public Directory**.
162
+
163
+There is a directory by the name of your user, which contains a file.
164
+Please copy this into some custom project folder in your home directory.
165
+
166
+Using your debugging, observation, and analytical skills, unravel the
167
+puzzle until you have an ordered, plain text, english readable file
168
+(called **results**) with directions on how to submit the project.
169
+
170
+In many puzzles, one's visual comprehension of the scenario plays a vital
171
+role. Where something doesn't necessarily meet the eye, or is not
172
+behaving as you would expect- just try reading any messages or output.
173
+Sometimes the clues are right under your nose.
174
+
175
+As is the case many investigations, just observing how things behave can
176
+lead to recognition of an object's true state, or the recognition of a
177
+pattern, which can be used to solve the task at hand.
178
+
179
+## VERIFICATION
180
+
181
+The **results** file, when correctly unscrambled and assembled, can be
182
+verified by generating its **md5sum** hash.
183
+
184
+This hash should match the hash stored inside the **MANIFEST** file
185
+located in the project directory (in the public directory).
186
+
187
+### FILECHK
188
+
189
+You can also use the **filechk** tool to verify the accuracy of your
190
+results:
191
+
192
+```
193
+lab46:~/src/SEMESTER/unix/pbx0$ filechk unix pbx0
194
+```
195
+
196
+## SUBMISSION
197
+
198
+In addition to the files produced during the completion of this project,
199
+I would also like for you to create a detailed step-by-step text file
200
+called **pbx0steps** which includes the valid command-lines that will
201
+document for me the steps you took from project commencement through
202
+completion. You will submit this file at the end in accordance with the
203
+instructions.
204
+
205
+To successfully complete this project, you must follow the directions
206
+located in a readable file at the conclusion of this project. Until you
207
+encounter it, you are not yet finished (hint).
208
+
209
+You should get some sort of confirmation indicating successful submission
210
+(actually, two) if all went according to plan. If not, check for typos
211
+and or locational mismatches.
212
+
213
+### SUBMIT TOOL USAGE
214
+
215
+Let's say you have completed work on the project, and are ready to
216
+submit, you would do the following:
217
+
218
+```
219
+lab46:~/src/SEMESTER/unix/pbx0$ submit unix pbx0 file1 file2 file3 ... fileN
220
+```
221
+
222
+A less abstract instantiation of the above (to help you transition):
223
+
224
+```
225
+lab46:~/src/SEMESTER/unix/pbx0$ submit unix pbx0 results pbx0steps
226
+Submitting unix project "pbx0":
227
+ -> results(OK)
228
+ -> pbx0steps(OK)
229
+
230
+SUCCESSFULLY SUBMITTED
231
+```
232
+
233
+You should get some sort of confirmation indicating successful submission
234
+if all went according to plan. If not, check for typos and or locational
235
+mismatches.
236
+
237
+I'll be looking for the following:
238
+
239
+### RUBRIC
240
+
241
+```
242
+104:pbx0:final tally of results (104/104)
243
+*:pbx0:submitted results file via submit tool [13/13]
244
+*:pbx0:submitted pbx0steps file via submit tool [13/13]
245
+*:pbx0:results md5sum matches project MANIFEST [13/13]
246
+*:pbx0:results is correctly unscrambled and assembled [13/13]
247
+*:pbx0:pbx0steps contains valid set of instructions [13/13]
248
+*:pbx0:pbx0steps any commentary after hash mark [13/13]
249
+*:pbx0:emailed results via instructions [13/13]
250
+*:pbx0:matching subject line as per instructions [13/13]
251
+```
252
+
253
+Additionally:
254
+ * Solutions not abiding by spirit of project will be subject to a 50% overall deduction
255
+ * Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
256
+ * Solutions not utilizing indentation to promote scope and clarity will be subject to a 25% overall deduction
257
+ * Solutions not organized and easy to read are subject to a 25% overall deduction