=====================================================================
 LAB 02 - SNMP-BASED NETWORK DEVICE MONITORING  -  HOW TO RUN
=====================================================================
Scenario : SNMP-enabled Linux server acting as a simulated switch
           (agent = net-snmp "snmpd", manager = snmpget / snmpwalk + Python)
Tested on: Ubuntu / Debian (works on any distro with net-snmp 5.x)

FILES
-----
 config.env            Target IP, community string, sample interval
 setup_snmpd.sh        Installs + configures snmpd (read-only agent)
 task1_snmpget.sh      Task 1 : sysName, sysDescr, sysUpTime via snmpget
 task2_snmpwalk.sh     Task 2 : interface status, octets, info via snmpwalk
 task3_throughput.py   Task 3 : throughput (bps) and % utilisation, 2 samples
 task4_anomaly.py      Task 4 : abnormal-condition detection + alert thresholds
 snmp_utils.py         Helper module (calls snmpget/snmpwalk, parses output)
 generate_traffic.sh   Makes loopback traffic so Task 3 is non-zero
 create_fault.sh       Creates a down link for Task 4 (optional)
 run_all.sh            Runs Tasks 1-4 in order
 VIVA.txt              Viva questions and model answers
 output/               Results are saved here (created on run)
 sample_output/        Example run captured on a test VM (yours will differ)

STEP 0 - PREREQUISITES
----------------------
 Linux terminal with sudo, python3 (3.6+). Nothing else to pip-install.

STEP 1 - INSTALL AND START THE SNMP AGENT
-----------------------------------------
   unzip snmp_lab02.zip && cd snmp_lab02
   sudo bash setup_snmpd.sh

 Check it is running:
   systemctl status snmpd            (or:  pgrep -a snmpd)
 Quick test (MIB name):
   snmpget -v2c -c labpublic 127.0.0.1 SNMPv2-MIB::sysName.0
   -> SNMPv2-MIB::sysName.0 = STRING: LAB-SW01
 Same thing with the numeric OID:
   snmpget -v2c -c labpublic 127.0.0.1 .1.3.6.1.2.1.1.5.0

 MIB NAMES vs NUMERIC OIDs
   The scripts use MIB NAMES (e.g. SNMPv2-MIB::sysName.0, IF-MIB::ifInOctets).
   The matching numeric OID is kept in a comment (#) next to every command/line.
   setup_snmpd.sh installs the MIB files (snmp-mibs-downloader) and enables them.
   Manual install if you skip setup_snmpd.sh:
     sudo apt install snmp-mibs-downloader     (needs the multiverse/non-free repo)
     sudo sed -i 's/^mibs :/# mibs :/' /etc/snmp/snmp.conf
   MIBs cannot be installed? Use numeric: in task1_snmpget.sh comment the three MIB lines
   and uncomment the three numeric lines; for Task 2/3/4 replace the name with the number
   shown in the comment (snmp_utils.py -> OID{} table).
   Useful: snmptranslate -On SNMPv2-MIB::sysName.0   (name -> number)
           snmptranslate .1.3.6.1.2.1.1.5.0          (number -> name)

STEP 2 - TASK 1 (2 marks): snmpget
----------------------------------
   bash task1_snmpget.sh
 Take a screenshot showing sysName, sysDescr, sysUpTime.
 MIB names: SNMPv2-MIB::sysDescr.0 | sysUpTime.0 | sysName.0
 Numeric  : sysDescr 1.3.6.1.2.1.1.1.0 | sysUpTime 1.3.6.1.2.1.1.3.0 | sysName 1.3.6.1.2.1.1.5.0
 The wrong-community test at the end proves SNMP authentication-by-community.
 Output saved: output/task1_snmpget.txt

STEP 3 - TASK 2 (3 marks): snmpwalk
-----------------------------------
   bash task2_snmpwalk.sh
 Walks ifDescr, ifType, ifMtu, ifSpeed, ifPhysAddress, ifAdminStatus,
 ifOperStatus, ifIn/OutOctets (32-bit), ifHCIn/OutOctets (64-bit), errors, discards,
 then prints a neat summary table.
 Output saved: output/task2_snmpwalk.txt
 Handy single commands:
   snmpwalk -v2c -c labpublic 127.0.0.1 IF-MIB::ifTable      # whole ifTable   (1.3.6.1.2.1.2.2)
   snmpwalk -v2c -c labpublic 127.0.0.1 IF-MIB::ifXTable     # 64-bit counters (1.3.6.1.2.1.31.1.1)

STEP 4 - TASK 3 (3 marks): throughput and utilisation
-----------------------------------------------------
 Terminal A:   python3 task3_throughput.py 10        (10 s between samples)
 Terminal B (start immediately after A):   bash generate_traffic.sh 20
 Formulae used:
   delta        = octets2 - octets1   (+2^32 / 2^64 if the counter wrapped)
   throughput   = delta x 8 / seconds              [bit/s]
   utilisation  = throughput / ifSpeed x 100       [%]
 Output saved: output/task3_throughput.txt (the "Worked example" at the end of the
 run is what you copy into the report).
 NOTE: loopback (lo) reports ifSpeed = 10 Mbit/s, so heavy traffic can exceed 100%.
       Interfaces reporting speed 0 (virtual NICs such as eth0 in VMs/containers)
       show "n/a" - use lo or a physical NIC for percentage figures.

STEP 5 - TASK 4 (3 marks): abnormal condition + alert threshold
---------------------------------------------------------------
   python3 task4_anomaly.py 10
 Detects: admin-up/oper-down link, error rate, discard rate, high utilisation,
 and prints the recommended thresholds (warning / critical / polling).

STEP 6 - CREATE A REAL ABNORMAL CONDITION (optional, recommended)
-----------------------------------------------------------------
   sudo bash create_fault.sh up         # veth0 admin-UP, oper-DOWN (peer is down)
   python3 task4_anomaly.py 5           # -> [CRITICAL] veth0: admin=up but oper=down
   sudo bash create_fault.sh clean      # remove it
 No root / no "ip" command?  Use the simulated fault:
   python3 task4_anomaly.py 5 --demo
 (Also try high utilisation: run  bash generate_traffic.sh 30  while Task 4 runs.)

RUN EVERYTHING
--------------
   bash run_all.sh        (≈ 25 s)

TROUBLESHOOTING
---------------
 "Timeout: No Response"            -> snmpd not running, wrong community, firewall UDP/161,
                                      or HOST wrong in config.env
 "Unknown Object Identifier"       -> MIBs not installed/enabled: see "MIB NAMES vs NUMERIC OIDs"
                                      above (or switch to the numeric OIDs kept in the comments)
 "command not found: snmpget"      -> sudo apt install snmp
 Counters never change             -> start generate_traffic.sh during sampling
 Only listening on localhost?      -> /etc/snmp/snmpd.conf: agentaddress udp:161
                                      (default Debian config binds 127.0.0.1 only)
 Packet capture (extra evidence):  sudo tcpdump -i lo -n udp port 161

SECURITY NOTE
-------------
 SNMP v1/v2c send the community string in clear text. In production use SNMPv3
 (authPriv). Never expose a "public" read-write community.

SUGGESTED REPORT STRUCTURE
--------------------------
 1. Objective & setup (diagram: manager --UDP 161--> agent)   2. Task 1 screenshot + OIDs
 3. Task 2 screenshots + summary table                         4. Task 3 sample table + worked calc
 5. Task 4 finding, thresholds and justification               6. Conclusion
