diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index 7b2f604..c7bcb2f 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -17,7 +17,7 @@ jobs: - name: Check out repository uses: actions/checkout@v4 - - name: Validate maintained Markdown structure + - name: Validate Markdown structure shell: bash run: | python - <<'PY' @@ -25,27 +25,26 @@ jobs: import re import sys - files = [ - "README.md", - "CONTRIBUTING.md", - "STYLE_GUIDE.md", - "visual-guides.md", - "arista.md", - "aws.md", - "azure.md", - "cisco.md", - "docker.md", - "git.md", - "google-cloud.md", - "iptables.md", - "kubernetes.md", - "leaf-spine.md", - "linux-boot.md", - "pulumi.md", - "rest-api.md", - "spanning-tree.md", - "terraform.md", - ] + required_root = { + Path("README.md"), + Path("CONTRIBUTING.md"), + Path("STYLE_GUIDE.md"), + } + allowed_root_markdown = {path.name for path in required_root} + allowed_domains = { + "networking", + "network-platforms", + "cisco-contact-center", + "cloud", + "containers", + "automation", + "linux", + "high-availability", + "development", + } + + docs = sorted(Path("docs").rglob("*.md")) + files = sorted(required_root) + docs supported_mermaid = re.compile( r"^(flowchart|graph|sequenceDiagram|stateDiagram-v2|" @@ -53,15 +52,41 @@ jobs: ) errors = [] - for filename in files: - path = Path(filename) + + unexpected_root = { + path.name + for path in Path(".").glob("*.md") + if path.name not in allowed_root_markdown + } + if unexpected_root: + errors.append( + "Unexpected root Markdown files: " + + ", ".join(sorted(unexpected_root)) + ) + + if not docs: + errors.append("docs/: no Markdown reference files found") + + for path in docs: + relative = path.relative_to("docs") + if len(relative.parts) == 1: + if relative.name != "visual-guides.md": + errors.append( + f"{path}: only visual-guides.md may live directly under docs/" + ) + elif len(relative.parts) != 2: + errors.append(f"{path}: references must use docs//.md") + elif relative.parts[0] not in allowed_domains: + errors.append(f"{path}: unknown documentation domain") + + for path in files: if not path.is_file(): - errors.append(f"{filename}: file is missing") + errors.append(f"{path}: file is missing") continue text = path.read_text(encoding="utf-8") if not text.strip(): - errors.append(f"{filename}: file is empty") + errors.append(f"{path}: file is empty") continue first_content_line = next( @@ -69,13 +94,13 @@ jobs: "", ) if not first_content_line.startswith("# "): - errors.append(f"{filename}: first content line must be an H1") + errors.append(f"{path}: first content line must be an H1") if "\x00" in text: - errors.append(f"{filename}: NUL byte found") + errors.append(f"{path}: NUL byte found") for number, line in enumerate(text.splitlines(), start=1): if re.search(r"\[[^\]]*\]\(\s*\)", line): - errors.append(f"{filename}:{number}: empty Markdown link") + errors.append(f"{path}:{number}: empty Markdown link") opening_count = text.count("```mermaid") mermaid_blocks = re.findall( @@ -84,7 +109,7 @@ jobs: flags=re.DOTALL, ) if opening_count != len(mermaid_blocks): - errors.append(f"{filename}: unclosed Mermaid code fence") + errors.append(f"{path}: unclosed Mermaid code fence") for index, block in enumerate(mermaid_blocks, start=1): first_line = next( @@ -93,7 +118,7 @@ jobs: ) if not supported_mermaid.match(first_line): errors.append( - f"{filename}: Mermaid block {index} has an unsupported " + f"{path}: Mermaid block {index} has an unsupported " f"or missing diagram declaration: {first_line!r}" ) @@ -101,7 +126,7 @@ jobs: print("\n".join(errors)) sys.exit(1) - print(f"Validated {len(files)} maintained Markdown files.") + print(f"Validated {len(files)} Markdown files across {len(docs)} references.") PY links: @@ -110,30 +135,12 @@ jobs: - name: Check out repository uses: actions/checkout@v4 - - name: Check maintained documentation links + - name: Check documentation links uses: lycheeverse/lychee-action@v2 with: args: >- --offline --verbose --no-progress - README.md - CONTRIBUTING.md - STYLE_GUIDE.md - visual-guides.md - arista.md - aws.md - azure.md - cisco.md - docker.md - git.md - google-cloud.md - iptables.md - kubernetes.md - leaf-spine.md - linux-boot.md - pulumi.md - rest-api.md - spanning-tree.md - terraform.md - fail: true \ No newline at end of file + './**/*.md' + fail: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6fdce2..d74e9f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,46 @@ Corrections and focused additions are welcome. The goal is operationally useful, 4. Mark destructive commands clearly and include a safer inspection step first. 5. Never commit real credentials, internal addresses, customer data, private architecture, or employer-specific interview material. +## Choose the correct location + +Reference sheets belong under a shallow domain directory: + +```text +docs//.md +``` + +Current domains are: + +- `networking` +- `network-platforms` +- `cisco-contact-center` +- `cloud` +- `containers` +- `automation` +- `linux` +- `high-availability` +- `development` + +Use the closest existing domain instead of creating a one-file directory. Add a new domain only when multiple related references justify it. Keep `README.md`, `CONTRIBUTING.md`, `STYLE_GUIDE.md`, and `LICENSE` at the repository root. + +## Name the file intentionally + +Use the canonical name engineers are likely to search for: + +- common, unambiguous protocol acronyms: `tcp.md`, `udp.md`, `ospf.md`, `lldp.md`; +- descriptive names for ambiguous concepts: `spanning-tree.md`, `osi-model.md`; +- actual platform names: `arista-eos.md`, `cisco-ios.md`, `fortigate.md`, `junos.md`; +- concise product acronyms inside an already specific folder: `docs/cisco-contact-center/cvp.md`. + +Do not rename files solely to make everything an acronym or solely to spell everything out. Optimize for clarity, searchability, and domain context. + +When adding, moving, or renaming a sheet: + +1. update the root README index; +2. update all relative cross-references; +3. keep the hierarchy shallow; +4. ensure documentation-quality checks pass. + ## Cheat-sheet structure Use the following order when it fits the topic: @@ -39,6 +79,14 @@ A read-only, least-disruptive-first sequence. - [Documentation title](https://example.com) ``` +When inherited content has only received a structural cleanup and has not been technically revalidated, use: + +```markdown +> **Status:** Legacy reference — technical validation pending +``` + +Do not assign a fresh review date to unvalidated content. + ## Style rules - Use one `#` heading per document. @@ -58,4 +106,4 @@ A pull request should explain: - which official references were used; - how the examples were validated. -For a simple typo or broken link, a short explanation is sufficient. \ No newline at end of file +For a simple typo or broken link, a short explanation is sufficient. diff --git a/README.md b/README.md index 4254222..0e0174c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Infrastructure and Network Engineering Cheatsheets +# Infrastructure Reference Practical quick-reference notes for network engineering, Linux operations, cloud platforms, infrastructure automation, and troubleshooting. @@ -7,11 +7,12 @@ Practical quick-reference notes for network engineering, Linux operations, cloud ## How to use this repository +- Browse references by domain under [`docs/`](docs/). - Replace values such as ``, ``, and `` before running commands. - Start with read-only inspection commands and capture the current state. - Treat `clear`, `delete`, `destroy`, `flush`, `reset`, `prune`, and `--force` operations as destructive. - Prefer official documentation for release-specific behavior. -- Use [visual-guides.md](visual-guides.md) for topology, lifecycle, state-transition, and troubleshooting diagrams. +- Use [the visual guides](docs/visual-guides.md) for topology, lifecycle, state-transition, and troubleshooting diagrams. - Open a content-correction issue when a command is obsolete, unsafe, ambiguous, or vendor-specific. ## Visual guides @@ -20,99 +21,119 @@ The diagrams are intentionally limited to concepts where visual relationships im | Concept | Visual reference | Detailed reference | |---|---|---| -| Spanning-tree root and alternate path | [Visual guide](visual-guides.md#spanning-tree-root-and-alternate-path) | [spanning-tree.md](spanning-tree.md) | -| Leaf-spine topology | [Visual guide](visual-guides.md#leaf-spine-fabric) | [leaf-spine.md](leaf-spine.md) | -| Pulumi change lifecycle | [Visual guide](visual-guides.md#pulumi-change-lifecycle) | [pulumi.md](pulumi.md) | -| Linux boot sequence | [Visual guide](visual-guides.md#linux-boot-sequence) | [linux-boot.md](linux-boot.md) | -| Git branch and pull-request workflow | [Visual guide](visual-guides.md#git-branch-and-pull-request-workflow) | [git.md](git.md) | -| Operational troubleshooting sequence | [Visual guide](visual-guides.md#operational-troubleshooting-sequence) | [STYLE_GUIDE.md](STYLE_GUIDE.md) | +| Spanning-tree root and alternate path | [Visual guide](docs/visual-guides.md#spanning-tree-root-and-alternate-path) | [Spanning Tree](docs/networking/spanning-tree.md) | +| Leaf-spine topology | [Visual guide](docs/visual-guides.md#leaf-spine-fabric) | [Leaf-spine design](docs/networking/leaf-spine.md) | +| Pulumi change lifecycle | [Visual guide](docs/visual-guides.md#pulumi-change-lifecycle) | [Pulumi](docs/automation/pulumi.md) | +| Linux boot sequence | [Visual guide](docs/visual-guides.md#linux-boot-sequence) | [Linux boot and kernel](docs/linux/linux-boot.md) | +| Git branch and pull-request workflow | [Visual guide](docs/visual-guides.md#git-branch-and-pull-request-workflow) | [Git](docs/development/git.md) | +| Operational troubleshooting sequence | [Visual guide](docs/visual-guides.md#operational-troubleshooting-sequence) | [Documentation style guide](STYLE_GUIDE.md) | ## Networking fundamentals | Topic | Reference | |---|---| -| Clos fabrics | [clos.md](clos.md) | -| Leaf-spine design | [leaf-spine.md](leaf-spine.md) | -| LLDP | [lldp.md](lldp.md) | -| OSI model | [osi.md](osi.md) | -| OSPF | [ospf.md](ospf.md) | -| Spanning Tree Protocol | [spanning-tree.md](spanning-tree.md) | -| TCP | [tcp.md](tcp.md) | -| UDP | [udp.md](udp.md) | +| Clos fabrics | [docs/networking/clos.md](docs/networking/clos.md) | +| Leaf-spine design | [docs/networking/leaf-spine.md](docs/networking/leaf-spine.md) | +| LLDP | [docs/networking/lldp.md](docs/networking/lldp.md) | +| OSI model | [docs/networking/osi-model.md](docs/networking/osi-model.md) | +| OSPF | [docs/networking/ospf.md](docs/networking/ospf.md) | +| Spanning Tree | [docs/networking/spanning-tree.md](docs/networking/spanning-tree.md) | +| TCP | [docs/networking/tcp.md](docs/networking/tcp.md) | +| UDP | [docs/networking/udp.md](docs/networking/udp.md) | ## Network platforms and routing software | Platform | Reference | |---|---| -| Arista EOS | [arista.md](arista.md) | -| BIRD | [bird.md](bird.md) | -| Cisco IOS / IOS XE | [cisco.md](cisco.md) | -| Fortinet FortiGate | [fortinet.md](fortinet.md) | -| Juniper Junos | [juniper.md](juniper.md) | +| Arista EOS | [docs/network-platforms/arista-eos.md](docs/network-platforms/arista-eos.md) | +| BIRD | [docs/network-platforms/bird.md](docs/network-platforms/bird.md) | +| Cisco IOS / IOS XE | [docs/network-platforms/cisco-ios.md](docs/network-platforms/cisco-ios.md) | +| FortiGate | [docs/network-platforms/fortigate.md](docs/network-platforms/fortigate.md) | +| Junos | [docs/network-platforms/junos.md](docs/network-platforms/junos.md) | ## Cisco contact center | Product | Reference | |---|---| -| Cisco Unified Intelligence Center | [cisco-cuic.md](cisco-cuic.md) | -| Cisco Unified Customer Voice Portal | [cisco-cvp.md](cisco-cvp.md) | -| Cisco Intelligent Contact Management | [cisco-icm.md](cisco-icm.md) | +| Cisco Unified Intelligence Center | [docs/cisco-contact-center/cuic.md](docs/cisco-contact-center/cuic.md) | +| Cisco Unified Customer Voice Portal | [docs/cisco-contact-center/cvp.md](docs/cisco-contact-center/cvp.md) | +| Cisco Intelligent Contact Management | [docs/cisco-contact-center/icm.md](docs/cisco-contact-center/icm.md) | ## Cloud platforms | Platform | Reference | |---|---| -| Amazon Web Services and AWS CLI | [aws.md](aws.md) | -| Microsoft Azure and Azure CLI | [azure.md](azure.md) | -| Google Cloud and Google Cloud CLI | [google-cloud.md](google-cloud.md) | +| Amazon Web Services and AWS CLI | [docs/cloud/aws.md](docs/cloud/aws.md) | +| Microsoft Azure and Azure CLI | [docs/cloud/azure.md](docs/cloud/azure.md) | +| Google Cloud and Google Cloud CLI | [docs/cloud/google-cloud.md](docs/cloud/google-cloud.md) | -## Containers, orchestration, and infrastructure as code +## Containers and orchestration | Topic | Reference | |---|---| -| Docker and Docker Compose | [docker.md](docker.md) | -| Kubernetes and kubectl | [kubernetes.md](kubernetes.md) | -| Pulumi | [pulumi.md](pulumi.md) | -| Terraform | [terraform.md](terraform.md) | -| Jenkins CI/CD | [jenkins-cicd.md](jenkins-cicd.md) | -| Puppet | [puppet.md](puppet.md) | +| Docker and Docker Compose | [docs/containers/docker.md](docs/containers/docker.md) | +| Kubernetes and kubectl | [docs/containers/kubernetes.md](docs/containers/kubernetes.md) | + +## Infrastructure automation + +| Topic | Reference | +|---|---| +| Pulumi | [docs/automation/pulumi.md](docs/automation/pulumi.md) | +| Terraform | [docs/automation/terraform.md](docs/automation/terraform.md) | +| Jenkins | [docs/automation/jenkins.md](docs/automation/jenkins.md) | +| Puppet | [docs/automation/puppet.md](docs/automation/puppet.md) | ## Linux and operations | Topic | Reference | |---|---| -| awk | [awk.md](awk.md) | -| Debian | [debian.md](debian.md) | -| HAProxy | [haproxy.md](haproxy.md) | -| iptables | [iptables.md](iptables.md) | -| Linux boot and kernel | [linux-boot.md](linux-boot.md) | -| nmap | [nmap.md](nmap.md) | -| Pacemaker | [pacemaker.md](pacemaker.md) | -| Corosync | [corosync.md](corosync.md) | -| Regular expressions | [regex.md](regex.md) | -| SCP | [scp.md](scp.md) | -| sed | [sed.md](sed.md) | -| Xen | [xen.md](xen.md) | +| awk | [docs/linux/awk.md](docs/linux/awk.md) | +| Debian | [docs/linux/debian.md](docs/linux/debian.md) | +| HAProxy | [docs/linux/haproxy.md](docs/linux/haproxy.md) | +| iptables | [docs/linux/iptables.md](docs/linux/iptables.md) | +| Linux boot and kernel | [docs/linux/linux-boot.md](docs/linux/linux-boot.md) | +| nmap | [docs/linux/nmap.md](docs/linux/nmap.md) | +| Regular expressions | [docs/linux/regex.md](docs/linux/regex.md) | +| SCP | [docs/linux/scp.md](docs/linux/scp.md) | +| sed | [docs/linux/sed.md](docs/linux/sed.md) | +| Xen | [docs/linux/xen.md](docs/linux/xen.md) | + +## High availability + +| Topic | Reference | +|---|---| +| Corosync | [docs/high-availability/corosync.md](docs/high-availability/corosync.md) | +| Pacemaker | [docs/high-availability/pacemaker.md](docs/high-availability/pacemaker.md) | ## Development and data | Topic | Reference | |---|---| -| Git | [git.md](git.md) | -| Kafka | [kafka.md](kafka.md) | -| REST APIs | [rest-api.md](rest-api.md) | -| SQL | [sql.md](sql.md) | +| Git | [docs/development/git.md](docs/development/git.md) | +| Kafka | [docs/development/kafka.md](docs/development/kafka.md) | +| REST APIs | [docs/development/rest-api.md](docs/development/rest-api.md) | +| SQL | [docs/development/sql.md](docs/development/sql.md) | + +## Repository layout + +Reference material uses a shallow `docs//.md` structure. Project-level files stay at the repository root: -## Filename conventions +```text +README.md +CONTRIBUTING.md +STYLE_GUIDE.md +LICENSE +docs/ +``` -New and renamed sheets use descriptive lowercase kebab-case names, such as `google-cloud.md`, `leaf-spine.md`, and `spanning-tree.md`. A platform overview and its primary CLI belong in one file when they serve the same operational audience. +Filenames use the canonical name engineers are likely to search for. Common, unambiguous acronyms remain short (`tcp.md`, `ospf.md`), while ambiguous concepts stay descriptive (`spanning-tree.md`, `osi-model.md`). Vendor references name the actual platform (`arista-eos.md`, `junos.md`) instead of only the company. ## Maintenance policy -Accuracy-sensitive documents should include an **Applies to** line and a **Last reviewed** date. A review date means the examples received a documentation review; it does not guarantee compatibility with every release or environment. +Technically revalidated documents include an **Applies to** line and a **Last reviewed** date. Inherited version-sensitive pages that have not yet been revalidated are labeled **Legacy reference — technical validation pending** rather than receiving a misleading review date. -Repository quality checks validate the maintained documentation surface on pull requests and changes to `main`. See [CONTRIBUTING.md](CONTRIBUTING.md) and [STYLE_GUIDE.md](STYLE_GUIDE.md) before adding or substantially rewriting a sheet. +Repository quality checks validate project documentation and every Markdown file under `docs/` on pull requests and changes to `main`. See [CONTRIBUTING.md](CONTRIBUTING.md) and [STYLE_GUIDE.md](STYLE_GUIDE.md) before adding or substantially rewriting a sheet. ## License -Content is available under the [MIT License](LICENSE). \ No newline at end of file +Content is available under the [MIT License](LICENSE). diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 98f46d9..4032fb3 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -4,31 +4,82 @@ Each file should help an engineer answer a specific operational question quickly. Prefer commands, decision points, expected output, and cautions over broad product descriptions. +## Repository and folder conventions + +Reference sheets live under a shallow domain hierarchy: + +```text +docs//.md +``` + +Keep project-level documentation and repository metadata at the root. Do not place ordinary reference sheets beside `README.md`. + +Folder rules: + +- Use an existing domain whenever it reasonably fits. +- Keep the hierarchy to `docs//`; avoid deeper nesting. +- Do not create a directory for a single vendor, command, or page unless multiple related references justify it. +- Keep closely coupled technologies together, such as Pacemaker and Corosync. +- Separate distinct operational domains, such as containers and automation. +- Update the README, cross-references, and CI rules in the same change when restructuring files. + ## Filename conventions -Use descriptive lowercase kebab-case filenames: +Use descriptive lowercase kebab-case filenames. Choose the canonical name engineers are most likely to search for. + +### Protocols and standards + +Use a well-known acronym when it is canonical and unambiguous: ```text -google-cloud.md -leaf-spine.md +lldp.md +ospf.md +tcp.md +udp.md +``` + +Use a descriptive name when the acronym is ambiguous or the qualifier is part of the concept: + +```text +osi-model.md spanning-tree.md +leaf-spine.md ``` -Rules: +Do not mechanically append redundant suffixes such as `-protocol` when the subject is already clear. `spanning-tree.md` is preferred over both `stp.md` and `spanning-tree-protocol.md` because it is searchable and avoids ambiguity with shielded twisted pair. + +### Vendors and products + +Name the actual platform or product, not merely the company: + +```text +arista-eos.md +cisco-ios.md +fortigate.md +junos.md +google-cloud.md +``` + +Within a domain-specific folder, omit redundant prefixes when the acronym is the normal product name: + +```text +docs/cisco-contact-center/cuic.md +docs/cisco-contact-center/cvp.md +docs/cisco-contact-center/icm.md +``` + +### General rules -- Use the product or protocol name an engineer is likely to search for. - Separate words with hyphens, not underscores or compressed spellings. -- Avoid filenames that are broader or narrower than the actual content. -- Do not name a Git reference `github.md` unless the document is specifically about GitHub rather than Git. +- Avoid filenames broader or narrower than the actual content. - Combine a platform overview and its primary CLI when they serve the same audience and would otherwise repeat concepts. - Keep separate files when tools have different lifecycles, safety models, or operational workflows, such as Terraform and Pulumi. -- Avoid renaming stable single-word files only for cosmetic consistency. +- Avoid renaming stable single-word files solely for cosmetic consistency. +- When renaming or merging files, update the README, relative links, and documentation-quality checks in the same change. -When renaming or merging files, update the README, cross-references, and documentation-quality workflow in the same change. +## Required status metadata -## Required metadata for maintained sheets - -Place these lines immediately below the title: +New or technically revalidated sheets must place these lines immediately below the title: ```markdown > **Applies to:** Product family or major release @@ -37,6 +88,14 @@ Place these lines immediately below the title: Use `General concepts` when the material is standards-based rather than tied to one implementation. +An older page that has only been structurally cleaned up must not receive a false review date. Mark it clearly instead: + +```markdown +> **Status:** Legacy reference — technical validation pending +``` + +Do not add new unvalidated legacy pages. The legacy status exists only to make inherited content honest while it is being replaced or reviewed. + ## Command presentation Use angle-bracket placeholders: @@ -75,7 +134,7 @@ Guidelines: - Link visual guides to the detailed operational reference containing commands and cautions. - Prefer one focused diagram over a large all-in-one architecture drawing. -The repository-wide diagrams live in [visual-guides.md](visual-guides.md). Command-heavy cloud and utility sheets remain text-first unless a topology or lifecycle diagram adds clear operational value. Topic files may embed a diagram directly when it is essential to understanding that specific page. +The repository-wide diagrams live in [`docs/visual-guides.md`](docs/visual-guides.md). Command-heavy cloud and utility sheets remain text-first unless a topology or lifecycle diagram adds clear operational value. Topic files may embed a diagram directly when it is essential to understanding that specific page. ## Troubleshooting order @@ -99,4 +158,4 @@ Troubleshooting sections should generally proceed in this order: ## References -Prefer official project documentation, standards documents, vendor command references, and RFCs. Avoid copying large passages. Link to the authoritative source and summarize the operational implication. \ No newline at end of file +Prefer official project documentation, standards documents, vendor command references, and RFCs. Avoid copying large passages. Link to the authoritative source and summarize the operational implication. diff --git a/awk.md b/awk.md deleted file mode 100644 index e20a6c7..0000000 --- a/awk.md +++ /dev/null @@ -1,119 +0,0 @@ -### AWK Cheat Sheet - -#### Introduction to AWK - -AWK is a powerful text processing language, ideal for manipulating data files, extracting and formatting data, and producing reports. - -- **Purpose**: Text processing, data extraction, and reporting. - -#### AWK Commands - -**Print All Lines** - -- `awk '{print}' file.txt` -- Prints all lines in `file.txt`. - -**Print Specific Field** - -- `awk '{print $2}' file.txt` -- Prints the second field of each line in `file.txt`. - -**Sum a Column** - -- `awk '{sum += $1} END {print sum}' file.txt` -- Sums up the numbers in the first column of `file.txt`. - -**Print Lines Matching a Pattern** - -- `awk '/pattern/ {print}' file.txt` -- Prints lines that match 'pattern'. - -**Print Lines with More than N Fields** - -- `awk 'NF > N' file.txt` -- Prints lines with more than N fields. - -**Print Line Number with Each Line** - -- `awk '{print NR, $0}' file.txt` -- Prints each line preceded by its line number. - -**Print Last Field of Each Line** - -- `awk '{print $NF}' file.txt` -- Prints the last field of each line. - -**Replace or Substitute Text** - -- `awk '{gsub(/pattern/, "replacement"); print}' file.txt` -- Replaces 'pattern' with 'replacement' in `file.txt`. - -**Print Lines Where a Field Matches a Pattern** - -- `awk '$N ~ /pattern/' file.txt` -- Prints lines where the Nth field matches 'pattern'. - -**Split a Line into Array** - -- `awk '{split($0, array, ":"); print array[1]}' file.txt` -- Splits each line by ':' and prints the first element. - -#### Complex Data Processing - -**Pass Shell Variable to AWK** - -- `awk -v var="$shell_var" '{print var, $0}' file.txt` -- Passes a shell variable `shell_var` to AWK. - -**Perform Arithmetic Operations** - -- `awk '{print $1 * $2}' file.txt` -- Multiplies the first and second fields. - -**Print Lines If a Field is Within a Range** - -- `awk '$1 > 5 && $1 < 10' file.txt` -- Prints lines if the first field is between 5 and 10. - -**Conditional Statements** - -- `awk '{if ($1 > 10) print $1; else print $0}' file.txt` -- Prints the first field if it's greater than 10, otherwise prints the whole line. - -**Loop Through Fields in a Line** - -- `awk '{for (i=1; i<=NF; i++) print $i}' file.txt` -- Prints each field of a line on a new line. - -#### Advanced Text Processing - -**Print Lines Whose Field Matches a Regular Expression** - -- `awk '$1 ~ /^[a-zA-Z]+$/' file.txt` -- Prints lines where the first field contains only letters. - -**Aggregate Data Based on a Field** - -- `awk '{arr[$1] += $2} END {for (i in arr) print i, arr[i]}' file.txt` -- Sums the second field grouped by the first field. - -**Print Every Nth Line** - -- `awk 'NR % N == 0' file.txt` -- Prints every Nth line. - -**Print Lines Longer Than N Characters** - -- `awk 'length($0) > N' file.txt` -- Prints lines longer than N characters. - -**Convert CSV to Tab-Delimited** - -- `awk 'BEGIN {FS=","; OFS="\t"} {print}' file.csv` -- Converts a CSV file to tab-delimited format. - -#### Tips for Using AWK - -- **Regular Expressions**: Mastering regular expressions enhances AWK's power. -- **Script Files**: For complex operations, write AWK commands in a script file. -- **Testing**: Test AWK commands on sample data before applying to important files. diff --git a/cisco-cuic.md b/cisco-cuic.md deleted file mode 100644 index bfb9a0f..0000000 --- a/cisco-cuic.md +++ /dev/null @@ -1,111 +0,0 @@ -# **Cisco Unified Intelligence Center (CUIC)** - -- **Purpose**: CUIC is a comprehensive, web-based reporting solution designed for the management and operational reporting needs of Cisco contact centers. -- **Functionality**: It provides real-time and historical data reporting, allowing managers and supervisors to monitor key performance indicators (KPIs) and make informed decisions. It's customizable and user-friendly, enabling users to create, modify, and share reports. -- **Integration**: CUIC is designed to work with other Cisco products like Cisco Unified Contact Center Enterprise (UCCE) and Express (UCCX), as well as CVP and ICM. - ---- - -#### Implementation - -1. **Architecture**: CUIC is a web-based reporting solution. It's typically deployed as part of a Cisco Unified Contact Center environment, integrating with systems like Unified Contact Center Enterprise (UCCE), Unified Contact Center Express (UCCX), and CVP. -2. **Components**: - - **Reporting Server**: The core of CUIC, responsible for data aggregation, report generation, and user interface. - - **Database Server**: Stores the historical and real-time data used for reporting. -3. **Integration**: CUIC pulls data from various sources within the Cisco contact center suite, such as call routing systems, IVR systems, and agent performance metrics. - -#### Licensing - -- CUIC licensing is usually bundled with the overall Cisco Contact Center solution licensing. It often depends on the scale of the deployment, the number of agents, and the feature set required. -- There are different licensing levels which may include standard reporting features and more advanced customization capabilities. - -#### Use Cases - -1. **Operational Reporting**: Provides real-time and historical data to help manage contact center operations, such as call volumes, service levels, and agent performance. -2. **Custom Reporting**: Allows for the creation of customized reports to meet specific business needs, which is vital for analyzing trends and making strategic decisions. -3. **Dashboard Views**: Enables supervisors and managers to have a real-time view of key performance indicators (KPIs) in a dashboard format. -4. **Data Export and Sharing**: Reports can be exported and shared in various formats, facilitating communication and analysis within the organization. - -#### Management - -1. **User Interface**: CUIC offers a web-based interface for creating, modifying, and viewing reports. It is designed to be user-friendly, allowing non-technical staff to handle basic reporting needs. -2. **Report Customization**: Administrators and authorized users can create custom reports and dashboards tailored to specific requirements. -3. **Security and Access Control**: Managing user access and permissions is crucial. CUIC allows for granular control over who can view or edit specific reports or data sets. -4. **Maintenance and Upgrades**: Regularly updating the CUIC software is important for security and functionality. This includes applying patches from Cisco and upgrading to newer versions as they become available. -5. **Integration Maintenance**: Ensuring ongoing compatibility and smooth data integration with other components of the Cisco contact center suite is essential. -6. **Performance Monitoring**: Monitoring the performance of the CUIC system, especially during high data load scenarios, is important to ensure timely and accurate report generation. - ---- - -### Common Problems and Fixes - -### Report Generation Issues - -- **Problem**: Reports not generating, displaying errors, or taking too long to load. -- **Fix**: Check if the CUIC server is experiencing high load or resource constraints. Verify the report query for any errors or inefficiencies. Ensure the database server is operational and accessible. - -### Data Accuracy and Consistency Issues - -- **Problem**: Reports showing inaccurate or inconsistent data. -- **Fix**: Verify the data source configurations. Ensure that CUIC is correctly integrated with data sources like UCCX, UCCE, or CVP. Check for any synchronization issues between these systems. Validate the logic and parameters used in custom report templates. - -### Access and Permission Issues - -- **Problem**: Users unable to access certain reports or functionalities. -- **Fix**: Review user roles and permissions in CUIC. Ensure that users are assigned appropriate roles that align with their job functions. Check for any recent changes in user accounts or group settings. - -### Dashboard and UI Issues - -- **Problem**: Problems with loading dashboards or user interface elements not functioning correctly. -- **Fix**: Clear browser cache and cookies, and try accessing CUIC from a different browser or machine. Check if there are any compatibility issues with the browser version. Ensure that the CUIC server's web services are running smoothly. - -### Performance Issues - -- **Problem**: CUIC is slow or unresponsive. -- **Fix**: Monitor the system's resource usage (CPU, memory, disk I/O). Scale up resources if necessary. Optimize database performance and consider implementing load balancing if the system is under heavy use. - -### Connectivity Issues - -- **Problem**: Issues connecting to CUIC from client machines. -- **Fix**: Check network connectivity and firewall settings. Ensure that the required ports for CUIC are open and accessible. Verify the server’s IP address and DNS settings. - -- --- - -### Key Components of CUIC Architecture - -1. **Reporting Server**: - - **Core Element**: The heart of CUIC, responsible for generating and presenting reports. - - **Functions**: Includes processing report requests, executing queries against the database, and rendering reports in the user interface. - - **Web-Based Interface**: Provides a web portal for users to access, create, and customize reports. -2. **Database Server**: - - **Data Storage**: Houses the operational and historical data needed for reports. - - **Integration**: Typically integrates with databases of other Cisco contact center solutions (like UCCX, UCCE, or CVP) to pull data. - - **Data Synchronization**: Ensures data is regularly updated and synchronized with source systems. -3. **CUIC Client**: - - **User Access Point**: Users interact with CUIC through a web browser. - - **Capabilities**: Users can view, customize, and manage reports and dashboards. - -### Network and Integration - -- **Connectivity**: CUIC must maintain robust network connections to source systems (like UCCE or UCCX) for data retrieval. -- **Data Sources**: Can connect to multiple data sources simultaneously, aggregating data across various contact center components. - -### Deployment Models - -1. **Standalone Deployment**: CUIC can operate independently for basic reporting needs. -2. **Integrated Deployment**: More commonly, CUIC is integrated with Cisco's contact center solutions for comprehensive reporting and analytics. - -### Scalability and High Availability - -- **Horizontal Scaling**: CUIC supports scaling out by adding more reporting servers to handle increased load. -- **Redundancy**: For high-availability setups, redundant servers can be deployed to ensure continuous operation. - -### Security Aspects - -- **User Authentication**: Supports integration with directory services for user authentication and management. -- **Data Security**: Implements roles and permissions to control access to sensitive data and reports. - -### Customization and Extensibility - -- **Report Customization**: Allows creating custom reports and dashboards tailored to specific organizational needs. -- **APIs for Integration**: Provides APIs for integration with third-party applications or for automating certain tasks. diff --git a/cisco-cvp.md b/cisco-cvp.md deleted file mode 100644 index a8292b6..0000000 --- a/cisco-cvp.md +++ /dev/null @@ -1,97 +0,0 @@ - -# **Cisco Unified Customer Voice Portal (CVP)**: - -- **Purpose**: Cisco Unified CVP is primarily a Voice Response Unit (IVR) system used in call centers. -- **Functionality**: It allows businesses to effectively route calls to the most appropriate agent and provides IVR services such as self-service options. CVP can use voice recognition and text-to-speech technologies to interact with callers. -- **Integration**: CVP is often integrated with other Cisco contact center products, such as ICM (Intelligent Contact Management), for comprehensive call routing and management. - ---- - -### Implementation - -1. **Architecture**: CVP operates in a distributed architecture. It's typically deployed alongside other components like a VoiceXML gateway (for voice processing), a media server (for playing audio files), and a call server (for call control and logic). -2. **Integration**: It integrates with various components of a call center infrastructure, such as the Cisco Unified Contact Center Enterprise (UCCE) or Cisco Unified Contact Center Express (UCCX) for call routing, and with external databases or web services for data-driven interactions. -3. **Deployment Models**: CVP can be deployed in different ways depending on the needs of the organization. Common models include standalone (where it functions as an IVR system) or integrated with a larger contact center solution. - -### Licensing - -- Cisco CVP licensing is typically based on concurrent call capacity. This means you purchase licenses based on the maximum number of simultaneous calls that the system will handle. -- There might be additional licenses required for specific features or integrations. - -### Use Cases - -1. **Interactive Voice Response (IVR)**: CVP is widely used for creating sophisticated IVR applications that enable self-service options for callers, such as checking account balances, making payments, or retrieving information from a database. -2. **Call Routing**: In conjunction with Cisco ICM, CVP can make decisions about how to route incoming calls based on various criteria like caller input, time of day, or caller history. -3. **Personalized Caller Experiences**: Integrating with databases and CRM systems, CVP can provide personalized experiences by recognizing the caller and tailoring the interaction accordingly. -4. **Automated Outbound Calling**: CVP can be used for proactive customer contact campaigns, like appointment reminders or promotional announcements. - -### Management - -1. **Administration**: CVP includes an administration interface for configuration and management. Administrators can create and modify IVR scripts, manage system settings, and configure integrations. -2. **Monitoring and Reporting**: Regular monitoring of system performance and call statistics is crucial. This includes keeping track of call volumes, call completion rates, and system errors. -3. **Maintenance**: Regular updates and patches from Cisco should be applied to ensure system security and efficiency. It's also important to manage the IVR scripts and audio files to keep the content up to date. - ---- - -### Common Problems and Fixes - -1. **IVR Script Errors**: - - **Problem**: Incorrect behavior or errors in IVR applications. - - **Fix**: Check and debug the IVR scripts. Ensure that they are correctly written and tested. Validate the logic and flow of the scripts, and make sure that external data sources used by the scripts are accessible and returning the expected data. -2. **Call Routing Issues**: - - **Problem**: Calls not being routed correctly or dropped. - - **Fix**: Verify the configuration in both CVP and the integrated call routing system (like Cisco ICM). Check the routing scripts and the rules defined. Ensure that the network connectivity between CVP, gateways, and other components is stable. -3. **Audio Quality Problems**: - - **Problem**: Poor audio quality or missing audio. - - **Fix**: Check the audio files used in IVR prompts to ensure they are not corrupted. Verify the codecs used and ensure compatibility. Check network performance, as issues like packet loss or jitter can affect voice quality. -4. **Voice Recognition Issues**: - - **Problem**: Inaccurate or non-functioning voice recognition. - - **Fix**: Ensure that the voice recognition engine is properly configured and trained. Test with various voice samples to identify if the issue is with specific accents or speech patterns. Adjust sensitivity settings if necessary. -5. **Integration with External Systems**: - - **Problem**: Failure in retrieving or sending data to external databases, CRM systems, or web services. - - **Fix**: Verify the network connectivity to these systems. Check the configuration for data exchange, such as API endpoints, database connections, and authentication. Ensure that the external systems are operational and responding correctly. -6. **Performance Issues**: - - **Problem**: Slowness or system overloads. - - **Fix**: Monitor system performance metrics to identify bottlenecks. This may involve increasing resources, optimizing scripts, or load balancing. Ensure that the system is not exceeding its licensed capacity for concurrent calls. -7. **Licensing Issues**: - - **Problem**: Features not working due to licensing problems. - - **Fix**: Check that all necessary licenses are valid and have not expired. Ensure that the system is not exceeding its licensed limits. - ---- - - ### Core Components of CVP Architecture - -1. **Call Server**: - - **Role**: Acts as the central point of control for call management. - - **Function**: It processes call control requests, executes VoiceXML applications, and interacts with external systems for data retrieval and call routing decisions. - - **Integration**: Works in conjunction with Cisco ICM/UCCE for advanced call routing. -2. **VoiceXML Gateway**: - - **Role**: Handles the telephony interface and media processing. - - **Function**: It converts VoiceXML documents into voice responses, playing prompts, and collecting input from callers. - - **Hardware/Software**: Can be a dedicated hardware appliance or a software-based solution integrated with routers. -3. **Media Server**: - - **Role**: Stores and manages audio files and dynamic TTS (Text-to-Speech) content. - - **Function**: Delivers pre-recorded announcements and dynamic content for IVR applications. -4. **Reporting Server**: - - **Role**: Provides detailed reporting and analytics. - - **Function**: Collects and processes data on call flows, caller interactions, and system performance. -5. **Operations Console**: - - **Role**: Centralized management interface. - - **Function**: Used for configuring and managing the CVP environment, including script management and system monitoring. - -### Network Considerations - -- **Scalability**: The CVP architecture is designed to scale horizontally. You can add more servers or resources to handle increased call volumes. -- **High Availability**: For mission-critical environments, CVP supports high-availability configurations to ensure continuous operation. Redundant components can be deployed to avoid single points of failure. -- **Network Integration**: It integrates with existing IP network infrastructures and supports SIP (Session Initiation Protocol) for signaling. -- **Security**: Security features like encryption and secure voice protocols are supported to protect sensitive data and comply with regulatory standards. - -### Deployment Models - -1. **Standalone Mode**: CVP operates as an IVR system independent of other Cisco Contact Center solutions. -2. **Comprehensive Mode**: Fully integrated with Cisco ICM/UCCE for complex call routing and queuing scenarios. - -### Advanced Features - -- **Speech Recognition and TTS**: CVP supports advanced speech recognition and TTS engines for natural language processing. -- **Web Services Integration**: Allows integration with external web services and databases for dynamic, data-driven interactions. diff --git a/cisco-icm.md b/cisco-icm.md deleted file mode 100644 index 010de84..0000000 --- a/cisco-icm.md +++ /dev/null @@ -1,124 +0,0 @@ -# Cisco Intelligent Contact Management (ICM) - -- **Purpose**: ICM is a sophisticated call routing system used in contact centers to direct incoming calls to the best available agent or service. -- **Functionality**: It includes features like skills-based routing, queue management, and network-to-desktop Computer Telephony Integration (CTI). ICM helps in reducing call handling times and improving customer satisfaction. -- **Integration**: ICM typically integrates with other systems like Automatic Call Distributors (ACD), Interactive Voice Response (IVR) systems including CVP, and CRM software. - -> **Related Cheat Sheets**: See [cisco-cuic.md](cisco-cuic.md) for Cisco Unified Intelligence Center (CUIC) reporting details, and [cisco-cvp.md](cisco-cvp.md) for Cisco Unified Customer Voice Portal (CVP) details. - ---- - -## Implementation - -1. **Network and Contact Center Integration**: ICM is implemented as a central component of a larger contact center solution. It integrates with various network elements, including Automatic Call Distributors (ACD), Interactive Voice Response (IVR) systems like CVP, and databases. -2. **Configuration and Scripting**: ICM's setup involves extensive configuration and scripting to define call routing logic and business rules. This includes setting up agents, queues, and routing strategies. -3. **Data Center Approach**: Typically, ICM is deployed in a data center environment, taking advantage of robust server and network infrastructure for reliability and scalability. - -## Licensing - -- ICM licensing is based on the size and complexity of the deployment, typically involving concurrent user licenses or licenses based on the volume of interactions managed. -- Contact your Cisco account team for current licensing models, as these may change between versions. - -## Use Cases - -1. **Advanced Call Routing**: Determines the best destination for incoming calls based on predefined criteria, such as agent skills, caller data, time of day, and business hours. -2. **Multi-Channel Integration**: Manages interactions across various channels, including voice, email, chat, and social media. -3. **Real-Time and Historical Reporting**: Provides comprehensive reporting capabilities to analyze contact center performance. (Reporting is surfaced via CUIC — see [cisco-cuic.md](cisco-cuic.md).) -4. **Skills-Based Routing**: Routes callers to agents with the specific skills required to handle their inquiry. -5. **Network-to-Desktop CTI**: Delivers caller data to the agent's desktop (screen pop) at the time the call is connected. - -## Management - -- **Routine Maintenance**: Regular updates and patches from Cisco are necessary to keep the system running efficiently and securely. -- **Configuration Management**: Ongoing management of routing scripts and contact center parameters to adapt to changing business needs. -- **Performance Monitoring**: Continuous monitoring of system performance and call handling metrics. -- **Script Administration**: ICM routing scripts define how calls are handled. Regular audits of routing logic are recommended to ensure scripts reflect current business requirements. - ---- - -## Architecture - -### Core Components - -1. **Router** - - The central component that makes real-time decisions on routing customer interactions. - - Processes call routing requests and determines the best target (queue, agent, or IVR) based on configured logic. - - Operates in a duplex (active/standby) configuration for high availability. - -2. **Logger** - - Records all routing decisions and transaction data for historical reporting and analysis. - - Maintains a database of routing activity used by reporting tools such as CUIC. - - Also operates in a duplex configuration. - -3. **Administrative Workstation (AW)** - - Provides the interface for configuration, scripting, and real-time monitoring. - - Used by administrators to create and maintain routing scripts, agent configurations, and system settings. - - Includes the Script Editor, Configuration Manager, and Distributor components. - -4. **Peripheral Gateways (PG)** - - Connect ICM to various contact center components like ACDs, IVRs, and databases. - - Act as the bridge between the ICM Router and telephony or media components. - - Types include ACD PG, IVR PG (for CVP integration), and Agent PG. - -5. **CTI Server** - - Provides real-time call and agent data to desktop applications via the CTI protocol. - - Enables screen pops, agent state monitoring, and call control from agent desktops. - -6. **CTI OS (CTI Object Server)** - - Middleware layer that simplifies integration between agent desktop applications and the CTI Server. - - Provides APIs and toolkits for building custom agent desktop applications. - -### Network Considerations - -- **Scalability**: ICM can scale to support large, distributed contact center environments spanning multiple sites and thousands of agents. -- **High Availability**: Designed for high availability with duplex components (dual Router, dual Logger) to minimize downtime. -- **Latency Sensitivity**: ICM is latency-sensitive. The network between ICM components (Router, Logger, PG) should have low latency — typically within the same data center or connected via low-latency WAN. - -### Integration Points - -- **CVP (Customer Voice Portal)**: ICM sends call routing instructions to CVP, which handles the IVR/VoiceXML interaction with the caller. -- **Unified CM (CUCM)**: ICM integrates with Cisco Unified Communications Manager for agent phone control and call routing to agent extensions. -- **UCCX/UCCE**: ICM is the routing engine within Unified Contact Center Enterprise (UCCE). UCCX has its own built-in routing engine. -- **Multi-Channel Integration**: Integrates with Email, Chat, and Social Media channels via Cisco's multichannel portfolio. -- **CRM Integration**: Can integrate with Salesforce, Microsoft Dynamics, and other CRM platforms via CTI adapters for screen pop and customer data lookup. - -### Security - -- **Data Security and Compliance**: Includes features to ensure the security and privacy of customer data. -- **Authentication**: ICM administrative interfaces integrate with Active Directory for user authentication. -- **Role-Based Access**: Granular role-based permissions control who can view or modify configurations and routing scripts. -- **Encrypted Communications**: Support for TLS encryption on inter-component communications. - ---- - -## Common Problems and Fixes - -### Call Routing Failures - -- **Problem**: Calls not routing correctly, going to wrong queues, or being dropped. -- **Fix**: Check ICM routing scripts for logic errors in Script Editor. Verify peripheral gateway connectivity. Review Router logs for routing decision details. Confirm that agents are logged in and in the correct skill groups. - -### Peripheral Gateway Connectivity Issues - -- **Problem**: PG reports disconnected or ICM loses visibility to ACDs or IVR systems. -- **Fix**: Check network connectivity between PG and ICM Router. Verify PG service health on the PG server. Review PG logs for error messages. Ensure firewall rules permit ICM-to-PG traffic on required ports. - -### CTI / Screen Pop Not Working - -- **Problem**: Agent desktops not receiving call data or screen pops failing. -- **Fix**: Verify CTI Server connectivity from agent workstations. Check CTI OS Server service health. Confirm the agent's desktop application is configured with the correct CTI Server address and port. Review agent login state in ICM. - -### Agent Reporting Discrepancies - -- **Problem**: Agent state or call counts in reports do not match actual activity. -- **Fix**: Verify Logger connectivity and database health. Check for data synchronization issues between ICM Logger and CUIC. Ensure peripheral gateways are reporting agent events correctly. - -### High Router CPU or Memory - -- **Problem**: ICM Router experiencing high resource utilization leading to routing delays. -- **Fix**: Review routing scripts for inefficient logic (e.g., excessive database lookups in the call path). Monitor call volume versus system capacity. Consider load balancing across multiple Router instances in large deployments. - -### Script Errors / Failed Routing Steps - -- **Problem**: Routing scripts failing at a specific step, resulting in calls going to error paths. -- **Fix**: Use Script Editor's simulation mode to trace script execution. Check external database connections referenced by the script. Verify that all referenced labels, skill groups, and services are correctly configured. diff --git a/clos.md b/clos.md deleted file mode 100644 index 77ba7cd..0000000 --- a/clos.md +++ /dev/null @@ -1,63 +0,0 @@ -### Clos Network Design Cheat Sheet - -#### Introduction to Clos Network - -**Clos Network Overview** - -- A Clos network is a multistage, scalable, and non-blocking network architecture. -- **Purpose**: Designed to facilitate efficient and high-capacity communication between a large number of network nodes. - -**Key Characteristics** - -- Consists of multiple stages of switches. -- Ensures a path for every pair of input and output without any blockage. -- Highly scalable and fault-tolerant. - -#### Components of a Clos Network - -**Input Stage** - -- The first layer of switches where data enters the network. - -**Intermediate Stage** - -- Middle layer(s) of switches that connect the input and output stages. -- Provides multiple paths for traffic to flow between the stages. - -**Output Stage** - -- The final layer of switches where data exits the network. - -#### Advantages of Clos Network - -- **Scalability**: Easily scales to accommodate more nodes and increased traffic. -- **Fault Tolerance**: Multiple paths between nodes enhance reliability. -- **High Throughput**: Designed to handle a large amount of traffic simultaneously. - -#### Implementing Clos Network - -**Design Considerations** - -- Determine the number of stages based on the network size and requirements. -- Calculate the number of switches and links needed for each stage. - -**Configuration** - -- Configure switches in each stage to ensure proper connectivity and load balancing. -- Implement routing protocols that support multipath routing. - -**Testing and Validation** - -- Test for non-blocking performance and redundancy. -- Validate the network's ability to handle expected traffic loads. - -#### Use Cases - -- **Data Centers**: Efficiently manages high-volume internal traffic. -- **Large Enterprise Networks**: Provides scalability and robustness for large-scale enterprise environments. - -#### Tips for Clos Network Design - -- **Capacity Planning**: Carefully plan the capacity to ensure non-blocking performance. -- **Redundancy**: Implement redundant paths to ensure network reliability. -- **Monitoring**: Continuously monitor network performance and make adjustments as needed. diff --git a/corosync.md b/corosync.md deleted file mode 100644 index 3a5820d..0000000 --- a/corosync.md +++ /dev/null @@ -1,39 +0,0 @@ -### Corosync Cheat Sheet - -#### Introduction to Corosync -Corosync is an open-source clustering service and a group communication system. It's used to implement high availability within applications and create redundant clusters. - -- **Purpose**: Provides a fault-tolerant layer for cluster communication. - -#### Key Concepts -- **Cluster Engine**: Manages cluster membership and facilitates consistent messaging. -- **Quorum**: Ensures that actions are taken only when a majority (quorum) of cluster members agree. -- **Totem Protocol**: Manages cluster membership and messaging. -- **Ring**: A logical network structure used by Corosync for communication. - -#### Basic Corosync Commands -- **corosync-cfgtool -s**: Displays the status of the Corosync ring. -- **corosync-quorumtool**: Displays the current quorum status of the cluster. -- **corosync-cmapctl**: Displays the Corosync configuration and runtime statistics. - -#### Configuration -- **corosync.conf**: The main configuration file for Corosync. -- **Nodes Configuration**: Define nodes with their node ID and ring addresses. -- **Totem Configuration**: Configure network and consensus settings. -- **Quorum Configuration**: Define quorum policies and settings. - -#### Cluster Management -- **Starting Corosync**: `systemctl start corosync` -- **Stopping Corosync**: `systemctl stop corosync` -- **Enabling Corosync at Boot**: `systemctl enable corosync` -- **Disabling Corosync at Boot**: `systemctl disable corosync` - -#### Troubleshooting -- **Logs**: Check Corosync logs in `/var/log/corosync/corosync.log`. -- **Ring Status**: Use `corosync-cfgtool -s` to check the status of the communication ring. -- **Quorum Status**: Use `corosync-quorumtool` to check if the cluster has quorum. - -#### Tips for Using Corosync -- **Regular Configuration Backup**: Keep backups of your `corosync.conf` file. -- **Monitoring**: Continuously monitor Corosync logs and status. -- **Integration with Pacemaker**: Often used in conjunction with Pacemaker for complete high availability solutions. diff --git a/jenkins-cicd.md b/docs/automation/jenkins.md similarity index 100% rename from jenkins-cicd.md rename to docs/automation/jenkins.md diff --git a/pulumi.md b/docs/automation/pulumi.md similarity index 100% rename from pulumi.md rename to docs/automation/pulumi.md diff --git a/puppet.md b/docs/automation/puppet.md similarity index 100% rename from puppet.md rename to docs/automation/puppet.md diff --git a/terraform.md b/docs/automation/terraform.md similarity index 100% rename from terraform.md rename to docs/automation/terraform.md diff --git a/docs/cisco-contact-center/cuic.md b/docs/cisco-contact-center/cuic.md new file mode 100644 index 0000000..1d4eea0 --- /dev/null +++ b/docs/cisco-contact-center/cuic.md @@ -0,0 +1,54 @@ +# Cisco Unified Intelligence Center + +> **Status:** Legacy reference — technical validation pending + +Cisco Unified Intelligence Center (CUIC) provides reporting and dashboards for Cisco contact-center deployments. Exact architecture, supported data sources, licensing, browser requirements, and administrative workflows vary substantially by CUIC and UCCE/UCCX release. + +## Typical responsibilities + +- real-time and historical contact-center reporting; +- supervisor and operations dashboards; +- report definitions, value lists, and collections; +- user roles, permissions, and report access; +- integration with contact-center historical and real-time data sources; +- export, scheduling, and distribution of reports where supported. + +## Operational checks + +Before changing a production CUIC environment, identify: + +- the exact CUIC and contact-center release; +- deployment model and node roles; +- data sources and database connectivity; +- replication or high-availability state; +- certificate and authentication dependencies; +- report ownership, permissions, and scheduling impact; +- current backups and rollback procedure. + +## Troubleshooting sequence + +1. Confirm whether the problem affects one user, one report, one data source, or the entire cluster. +2. Check node and service health using the version-specific administration tools. +3. Compare browser, authentication, role, and permission behavior across users. +4. Verify data-source reachability and credentials. +5. Compare report query timing with database and application logs. +6. Check certificates, DNS, time synchronization, and recent changes. +7. Validate fixes against a noncritical report before changing shared definitions. + +## Common symptom areas + +| Symptom | Checks | +|---|---| +| Report does not load | Data source, query, permissions, service health | +| Data appears stale | Data-source status, replication, collection interval, clock | +| User cannot see a report | Role, collection membership, object permissions | +| Dashboard is slow | Query design, database load, report filters, node resources | +| Scheduled report fails | Scheduler service, destination, credentials, storage, email relay | + +## Related references + +- [CVP](cvp.md) +- [ICM](icm.md) + +> [!NOTE] +> This page intentionally avoids version-specific procedures until they are revalidated against current Cisco documentation. Use the documentation set matching the exact deployed release before applying configuration or upgrade guidance. diff --git a/docs/cisco-contact-center/cvp.md b/docs/cisco-contact-center/cvp.md new file mode 100644 index 0000000..619af05 --- /dev/null +++ b/docs/cisco-contact-center/cvp.md @@ -0,0 +1,58 @@ +# Cisco Unified Customer Voice Portal + +> **Status:** Legacy reference — technical validation pending + +Cisco Unified Customer Voice Portal (CVP) provides voice self-service and call-treatment functions within Cisco contact-center environments. Deployments commonly integrate SIP call control, VoiceXML gateways, media services, speech resources, and Cisco routing components. + +## Typical components + +- Call Server for call-control and application coordination; +- VoiceXML gateways for media and VoiceXML execution; +- media servers for prompts and static content; +- Operations, Administration, Maintenance, and Provisioning interfaces; +- integration with ICM/UCCE routing; +- speech-recognition or text-to-speech services where deployed; +- reporting and operational data consumed by other Cisco components. + +Exact component names, supported deployment models, and scaling limits are release-specific. + +## Operational checks + +Before making a change, identify: + +- the exact CVP, UCCE, Unified CM, IOS, and gateway releases; +- SIP call path and dial-peer design; +- VoiceXML application and media-server dependencies; +- redundancy model and active call impact; +- certificate, DNS, NTP, and authentication dependencies; +- current call volume, license or capacity limits, and maintenance window; +- rollback and configuration-backup procedure. + +## Troubleshooting sequence + +1. Reproduce one call and record timestamps, calling number, called number, and correlation identifiers. +2. Determine the last component that processed the call successfully. +3. Trace SIP signaling across ingress gateway, CVP, Unified CM, and routing components. +4. Verify media, VoiceXML, and speech-resource reachability separately from call signaling. +5. Compare routing-script decisions with CVP and gateway logs. +6. Check DNS, certificates, time synchronization, codec, DTMF, and network quality. +7. Test the least disruptive correction on a controlled call path. + +## Common symptom areas + +| Symptom | Checks | +|---|---| +| Call fails before IVR | SIP routing, dial peers, Call Server, routing response | +| Prompts are missing | Media URL, HTTP reachability, file format, cache, permissions | +| DTMF is not recognized | DTMF method, codec, gateway configuration, application logic | +| Speech recognition fails | Speech server reachability, licenses, grammar, latency | +| One-way or poor audio | RTP path, NAT, firewall, codec, packet loss, jitter | +| Intermittent call drops | SIP timers, gateway resources, network loss, component health | + +## Related references + +- [CUIC](cuic.md) +- [ICM](icm.md) + +> [!NOTE] +> This page intentionally avoids version-specific configuration commands until they are revalidated against the Cisco documentation set matching the deployed release. diff --git a/docs/cisco-contact-center/icm.md b/docs/cisco-contact-center/icm.md new file mode 100644 index 0000000..c886d9c --- /dev/null +++ b/docs/cisco-contact-center/icm.md @@ -0,0 +1,58 @@ +# Cisco Intelligent Contact Management + +> **Status:** Legacy reference — technical validation pending + +Cisco Intelligent Contact Management (ICM) is the routing and orchestration layer used in Cisco Unified Contact Center Enterprise environments. It coordinates routing decisions across contact-center components, agents, queues, IVR systems, and external data sources. + +## Typical components + +- Router for real-time routing decisions; +- Logger for configuration and historical data; +- Administrative Workstation and Distributor services; +- Peripheral Gateways for integration with telephony, agent, and media systems; +- CTI services for agent-desktop and call-control integrations; +- routing scripts, skill groups, services, and precision-routing objects; +- duplex and geographically redundant components where supported. + +Exact roles, service names, database behavior, and redundancy requirements are release-specific. + +## Operational checks + +Before changing a production ICM environment, identify: + +- the exact UCCE/ICM release and patch level; +- duplex side and component health; +- Router, Logger, Distributor, and Peripheral Gateway relationships; +- current routing-script version and deployment history; +- database, DNS, NTP, certificate, and Active Directory dependencies; +- call-volume and capacity impact; +- current backups and rollback process. + +## Troubleshooting sequence + +1. Capture the affected call or agent identifiers and timestamps. +2. Confirm whether the issue affects routing, agent state, reporting, CTI, or one peripheral. +3. Check component and duplex health using the release-specific diagnostic tools. +4. Trace the routing script and identify the first unexpected branch or missing object. +5. Verify Peripheral Gateway and CTI connectivity. +6. Correlate Router, Logger, PG, and application logs by timestamp. +7. Validate any correction with a controlled test call before broad deployment. + +## Common symptom areas + +| Symptom | Checks | +|---|---| +| Calls route to the wrong target | Script logic, object configuration, schedules, skill state | +| Calls enter an error path | Missing labels, unavailable services, database or peripheral failure | +| Peripheral appears offline | Network path, service health, side selection, certificates, ports | +| Agent state is stale | Agent PG, CTI services, Unified CM integration, synchronization | +| Reporting does not match routing | Logger health, replication, reporting interval, data-source status | +| Router utilization is high | Script complexity, external lookups, call volume, component health | + +## Related references + +- [CUIC](cuic.md) +- [CVP](cvp.md) + +> [!NOTE] +> This page intentionally avoids version-specific commands and architectural limits until they are revalidated against the documentation set for the deployed Cisco release. diff --git a/aws.md b/docs/cloud/aws.md similarity index 100% rename from aws.md rename to docs/cloud/aws.md diff --git a/azure.md b/docs/cloud/azure.md similarity index 100% rename from azure.md rename to docs/cloud/azure.md diff --git a/google-cloud.md b/docs/cloud/google-cloud.md similarity index 100% rename from google-cloud.md rename to docs/cloud/google-cloud.md diff --git a/docker.md b/docs/containers/docker.md similarity index 100% rename from docker.md rename to docs/containers/docker.md diff --git a/kubernetes.md b/docs/containers/kubernetes.md similarity index 100% rename from kubernetes.md rename to docs/containers/kubernetes.md diff --git a/git.md b/docs/development/git.md similarity index 100% rename from git.md rename to docs/development/git.md diff --git a/kafka.md b/docs/development/kafka.md similarity index 100% rename from kafka.md rename to docs/development/kafka.md diff --git a/rest-api.md b/docs/development/rest-api.md similarity index 100% rename from rest-api.md rename to docs/development/rest-api.md diff --git a/sql.md b/docs/development/sql.md similarity index 100% rename from sql.md rename to docs/development/sql.md diff --git a/docs/high-availability/corosync.md b/docs/high-availability/corosync.md new file mode 100644 index 0000000..d4cd319 --- /dev/null +++ b/docs/high-availability/corosync.md @@ -0,0 +1,108 @@ +# Corosync Quick Reference + +> **Applies to:** Corosync 3.x concepts on modern Linux high-availability clusters +> **Last reviewed:** 2026-07-18 + +Corosync provides cluster membership, quorum, and group communication services. It is commonly paired with Pacemaker, which manages resources and service placement. + +## Core concepts + +| Concept | Purpose | +|---|---| +| Membership | Tracks which cluster nodes are currently participating | +| Quorum | Prevents unsafe cluster actions when sufficient votes are unavailable | +| Totem | Ordered group-communication protocol used by Corosync | +| KNET | Common transport layer for node-to-node communication | +| Votequorum | Quorum provider for node voting and expected-vote calculations | + +## Read-only inspection + +```bash +systemctl status corosync +corosync-cfgtool -s +corosync-quorumtool -s +corosync-cmapctl +journalctl -u corosync -b +``` + +When Pacemaker is present, also inspect the resource layer: + +```bash +crm_mon -1Arf +pcs status +``` + +Use the command available for the cluster's management stack. + +## Configuration locations + +Common files and directories include: + +```text +/etc/corosync/corosync.conf +/etc/corosync/authkey +/etc/corosync/uidgid.d/ +``` + +Configuration normally defines node identities, transport addresses, quorum behavior, logging, and the cluster name. + +> [!WARNING] +> Membership, quorum, vote, transport, and node-ID changes can split a cluster or cause resource fencing. Capture the current configuration and cluster state, verify fencing, and follow the platform's rolling-change procedure. + +## Quorum checks + +```bash +corosync-quorumtool -s +corosync-quorumtool -l +``` + +Confirm: + +- expected votes; +- total votes; +- quorum threshold; +- current membership; +- whether the cluster is quorate; +- qdevice participation where used. + +Do not casually configure a two-node cluster to ignore quorum. Pair the quorum design with functional fencing and application-specific failure testing. + +## Network troubleshooting + +1. Confirm node addressing and name resolution. +2. Check interface state, MTU, drops, and errors. +3. Verify required UDP traffic is permitted between every cluster node. +4. Compare `corosync.conf` node IDs and addresses on all nodes. +5. Review Corosync journal timestamps for membership changes and token timeouts. +6. Check clock synchronization and sustained latency or packet loss. +7. Confirm both cluster communication paths when redundant links are configured. + +Useful commands: + +```bash +ip -br address +ip -s link +ss -uanp +ping +journalctl -u corosync --since '