Build a Linux System Health Reporter

Create a Bash script that captures Linux health in a browser-based Ubuntu lab.

Introduction

30 Second Summary

A slow or unfamiliar computer gives you clues long before it fails. Those clues are often scattered across different screens.

In this project, you will build a Bash system health reporter inside an isolated Ubuntu Linux lab in GitHub Codespaces. The reporter captures system identity plus resource health in a reusable file.

What You'll Build

You will run health-report.sh in a browser terminal to see a labeled snapshot of the kernel, your identity, disk usage, and memory usage.

By the end of this project, you'll have:

Inspect the system to reveal your location, account identity, running processes, available disk space, and memory usage.
Capture a manual snapshot in manual-report.txt. Display it in the terminal whenever you need evidence.
Run a reusable reporter from health-report.sh. Save its latest output in report.txt for inspection or sharing.
Secret Mission: Add an Environment language: section with a pipeline that keeps lines containing LANG.

Are there any prerequisites?

You'll need a Mac with Google Chrome, internet access, and an email address. The project includes GitHub account creation with no local Linux setup needed.

Before We Start

This checkpoint locks in the purpose of your Linux system health reporter before any hands-on work begins. The snapshot covers kernel details, user identity, resource usage, and filtered language settings for administration troubleshooting.

Launch Your Ubuntu Administration Lab

Running administration commands directly on macOS can hide Linux-specific behavior. An isolated Ubuntu lab protects your Mac from practice changes.

Your access begins with a personal GitHub account in Google Chrome.

GitHub Codespaces gives you a blank lab in the Visual Studio Code web client. A kernel check proves that the remote system is ready.

In this step, get ready to:

Create a verified personal GitHub account.
Launch a blank Ubuntu GitHub Codespace.
Prove that the remote terminal runs Linux.

Create and verify your GitHub account

A personal GitHub account gives you access to the browser-hosted lab. GitHub requires a verified email address for the account.

Account setup happens on GitHub's page. Your password stays there.

The sign-up page also supports Continue with Google if you prefer that sign-up option.

Visit https://github.com/signup in Google Chrome.
Create a free personal account by following the prompts on GitHub's page.

GitHub requests email verification before your account is ready for the lab.

Open the verification message from GitHub in your email inbox.
Complete the email verification using the message.
Return to GitHub in Google Chrome.

You should see your signed-in GitHub page. Your verified account can now create the remote lab.

Account verification missing?

Check the spam or junk folder in your email inbox.
Return to the sign-up page to confirm that you used the correct email address.

Ask for help with verifying your GitHub account.

Launch a blank GitHub Codespace

A Codespace places an Ubuntu workspace inside a cloud container. Your browser connects to that workspace through the Visual Studio Code web client.

Why use a browser lab?

Your Mac stays unchanged while you practice Linux commands. You also avoid installing a local virtual machine.

The container is isolated from the outer host system. This makes it a safe place for the administration tasks in this project.

Visit https://github.com/codespaces in your signed-in Google Chrome window.
Select See all under Explore quick start templates.

The expanded gallery includes the blank template used for this lab.

Select Use this template under the blank template.

Allow a couple of minutes while GitHub provisions the workspace. A quiet setup screen during that time does not mean the process has stalled.

Wait for the Visual Studio Code web client to finish opening.

You should see a browser-based editor workspace for your blank Codespace.

Codespace not opening?

Reload the browser page once if the workspace stops progressing.
Return to https://github.com/codespaces to confirm that the new Codespace is listed.

Ask for help with opening your Codespace.

Confirm the terminal runs Linux

The integrated terminal is your command line inside the remote Codespace. A system-information command reveals which operating system receives your commands.

Open the integrated terminal from the top menu in the Visual Studio Code web client.

You should see a terminal prompt inside the editor.

Before you run the check, make a quick prediction about whether the result will describe your Mac or the remote lab:

Run the kernel check by entering this command:

uname -a

What does this command show?

The uname command asks the operating system for kernel details.
The -a option requests all available system information.

You'll see one line of kernel and system information that includes Linux. This proves that your commands are running in the remote Ubuntu environment.

Your administration lab is live. You can now practice Linux commands without changing your Mac.

No terminal output?

Click inside the integrated terminal before entering the command again.
Wait for the terminal prompt to return before retrying the check.

Ask for help with checking your Codespaces terminal.

Your browser-hosted Ubuntu lab is ready. Next up, you'll inspect its filesystem and system resources like an administrator.

Read the System Like an Administrator

Your GitHub Codespaces lab is running Linux. You proved that the remote environment responds like a Linux system.

Before changing a system, an administrator needs a quick picture of its current state. You will gather that picture with shell commands before saving it as a report.

In this step, get ready to:

Map your position in the Linux filesystem.
Read system identity and resource information.
Save a labeled manual health report.

Map your filesystem location

The filesystem hierarchy organizes every directory beneath a single starting point. These first commands show your current location before revealing the entries around you.

Show your current location in the terminal from earlier by running this command:

pwd

What does this command show?

The pwd command prints the path to your current directory. This path tells you where new files appear when you create them.

Reveal detailed directory entries by running this command:

ls -la

How does the detailed listing help?

The -l option expands each entry into a detailed row. Those rows include permissions and ownership. The -a option includes hidden entries.

Inspect the top level of the Linux filesystem by running this command:

ls /

What lives at the top level?

The / directory sits at the top of the Linux filesystem. Its entries separate different types of system data.

The /etc directory holds system configuration.
The /home directory holds user home directories.
The /tmp directory holds temporary files.
The /usr directory holds user programs.
The /var directory holds changing system data.

Inspect identity and resources

A system snapshot also needs evidence about its user context and available resources. These checks reveal who you are inside the Codespace before showing storage and memory usage.

Inspect your current user and groups by running this command:

id

What does your identity include?

The id command reports your current user. It also reports the groups associated with your session.

Inspect filesystem space usage by running this command:

df -h

How is disk usage displayed?

The df command reports space usage for visible filesystems. The -h option formats the sizes for easier reading.

Inspect free and used memory by running this command:

free -m

How is memory displayed?

The free command summarizes available memory. The -m option displays the values in megabytes.

Open the live process viewer by running this command:

top

What does the process viewer reveal?

The top command continuously refreshes process activity. Use it to spot which processes consume system resources.

Press q to quit the process viewer.

You return to the shell prompt after quitting the live display.

Still inside the process viewer?

Click inside the integrated terminal to give it keyboard focus.
Press q again.

Help me exit the process viewer.

Group the health checks into a report

Terminal commands normally send results to standard output. Redirection captures that output in a file so the snapshot remains available after the commands finish.

Create manual-report.txt with a grouped system snapshot by running this command:

{
  echo "Manual System Report"
  echo "System:"
  uname -a
  echo "Identity:"
  id
  echo "Disk:"
  df -h
  echo "Memory:"
  free -m
} > manual-report.txt

How does the report get created?

The braces collect every report command into one group. Each echo command adds a title or section label.

The > redirect sends the group's standard output into manual-report.txt. Running the block again replaces the previous file contents with a fresh snapshot.

Ask yourself which labeled heading appears first when you display the saved file.

Display the saved report by running this command:

cat manual-report.txt

What should you see?

You should see Manual System Report at the top. The current Codespace output fills each labeled section.

The System: section contains Linux system information.
The Identity: section contains your user and groups.
The Disk: section contains filesystem space usage.
The Memory: section contains memory usage.

Report missing or incomplete?

Run the grouped command block again if the report file is missing.
Compare every quote and brace with the reference below if a section is absent.

Help me fix my manual report.

That is a strong first win. Your Codespace now holds a labeled system snapshot that you can inspect from the terminal.

✔️ Awesome, I've got everything!

Your saved snapshot is ready. It begins with the report title before showing the four labeled sections.

ⓧ I'd like to double check the full code

Compare the grouped command that generated manual-report.txt with this reference:

{
  echo "Manual System Report"
  echo "System:"
  uname -a
  echo "Identity:"
  id
  echo "Disk:"
  df -h
  echo "Memory:"
  free -m
} > manual-report.txt

Your manual snapshot proves that each health check works. Next up, you will automate the same checks with a Bash script.

Automate the Report and Hit a Permission Barrier

Your manual snapshot proves that the right commands reveal a system's health. Repeating that grouped block for every check is inefficient.

A Bash script makes the report reusable. Linux file permissions determine whether the script can run directly.

In this step, get ready to:

Create a reusable system health reporter.
Remove the owner's execute permission.
Use direct execution to expose the permission barrier.

Create the reusable health reporter

A shebang tells Linux which interpreter should read a script. The remaining lines print a labeled health snapshot.

Return to the web editor's file sidebar.
Select the file creation icon at the top of the sidebar.
Type health-report.sh into the file name field.
Press Enter to create the file.
Add the reporter to health-report.sh by copying this code:

#!/bin/bash

echo "Linux System Health Report"
echo "=========================="
echo
echo "System:"
uname -a
echo
echo "Identity:"
id
echo
echo "Disk usage:"
df -h
echo
echo "Memory usage:"
free -m

What does this script do?

The #!/bin/bash line selects Bash as the interpreter for direct execution.
The first two echo lines create the report header.
The uname -a command reports system information.
The id command reports the current identity.
The df -h command reports disk usage.
The free -m command reports memory usage.
The blank echo calls separate the report sections.

Press Cmd+S (macOS) or Ctrl+S (Windows) to save health-report.sh.
Confirm that health-report.sh remains listed in the file sidebar.
Verify that the editor shows #!/bin/bash as the first line.

File missing or incomplete?

Confirm that the file name is exactly health-report.sh.
Replace incomplete contents with the complete script above.

Ask for help with checking your script file.

✔️ Awesome, I've got everything!

Your health-report.sh file is saved with the complete reporter.

ⓧ I'd like to double check the full code

The complete saved file should match this reference.

#!/bin/bash

echo "Linux System Health Report"
echo "=========================="
echo
echo "System:"
uname -a
echo
echo "Identity:"
id
echo
echo "Disk usage:"
df -h
echo
echo "Memory usage:"
free -m

Remove owner execute permission

A long file listing begins with permission characters. The owner's permission triplet records whether that owner can read, write, or execute the file.

Remove the owner's execute permission by running this command:

chmod u-x health-report.sh

What does this command change?

The u selects the file owner. The -x removes execute permission.

The script contents stay unchanged. Only the owner's execute permission changes.

Inspect the script's permissions by running this command:

ls -l health-report.sh

How do you read the result?

The long listing starts with the file's permission characters. Your output now shows the owner's permission triplet without x.

The missing x confirms that the owner cannot execute the script directly.

Still see owner execute permission?

Confirm that you removed execute permission from health-report.sh.
Check that your terminal is using the directory containing health-report.sh.

Ask for help with reading the permission triplet.

Test direct execution

The ./ prefix asks the shell to execute a file from the current directory. This test connects the permission listing to real runtime behavior.

Predict whether Linux can start the script while its owner execute permission is missing.
Test the script directly by running this command:

./health-report.sh

What does this test prove?

The shell blocks direct execution with an execution-permission error. The script remains intact.

This result connects the missing owner permission to the blocked command.

That blocked run is the intended result. You have diagnosed the permission barrier through evidence.

Leave the owner execute permission removed.
Avoid running the script through the Bash interpreter.

Did the script run instead?

Return to the permission-removal substep.
Confirm that you targeted health-report.sh.
Inspect the owner's permission triplet again.

Ask for help with diagnosing an unexpected successful run.

Your reusable reporter is in place. Next, you'll restore only its owner execute permission and generate the saved report.

Fix the Permission and Generate the Report

Your Bash reporter is complete. The previous step proved that Linux blocks direct execution while the owner execute permission is missing.

A least-privilege fix restores execution for the owner only. This keeps the group and other permissions unchanged.

In this step, get ready to:

Restore the owner execute permission.
Run the health reporter directly.
Save the latest report in report.txt.

Apply least privilege

Linux permissions can target the owner, the group, or everyone else. The symbolic mode u+x adds execute permission for the owner.

The ls -l listing exposes the permission triplets. This makes the permission change visible before you run the script.

Restore the owner's execute permission by running this command:

chmod u+x health-report.sh

What does this command change?

The chmod command changes file permissions. The u+x mode adds execute permission for the owner of health-report.sh.

The command leaves the group and other permissions unchanged. This gives the script only the access it needs.

Display the updated permissions by running this command:

ls -l health-report.sh

What does this command show?

The ls command displays the permissions attached to health-report.sh. The owner section now includes an execute marker.

You'll see x in the owner's permission triplet. No new execute permission appears for the group or everyone else.

Owner Execute Marker Still Missing?

Confirm that the integrated terminal is still in the folder containing health-report.sh.
Check that the permission mode uses a plus sign before x.

Help me diagnose the missing owner execute permission.

Run the reporter directly

Direct execution lets the shell launch the file according to its shebang. The #!/bin/bash line selects Bash as the interpreter.

Predict whether the shell will block the script or print the report.
Test the corrected permission by running this command:

./health-report.sh

Why Does Direct Execution Work Now?

The owner now has execute permission. The shebang tells Linux which interpreter should process the script.

The shell can launch ./health-report.sh directly. Each command sends its result to the terminal.

You've cleared the permission barrier. You'll see Linux System Health Report followed by System:, Identity:, Disk usage:, and Memory usage: sections.

Direct Execution Still Blocked?

Confirm that the owner's permission triplet still contains x.
Confirm that the first line of the script is #!/bin/bash.
Confirm that the filename is exactly health-report.sh.

Help me diagnose why direct execution is still blocked.

✔️ Awesome, I've got everything!

Great. The contents of health-report.sh remain unchanged. Only the file permission changed.

ⓧ I'd like to double check the full code

Compare your health-report.sh file with this complete version.

#!/bin/bash

echo "Linux System Health Report"
echo "=========================="
echo
echo "System:"
uname -a
echo
echo "Identity:"
id
echo
echo "Disk usage:"
df -h
echo
echo "Memory usage:"
free -m

Save the latest report

Standard output is the text a command sends to the terminal. Redirection with > writes that text into report.txt.

The && operator displays the file only after the script succeeds. This prevents a failed run from being presented as a fresh report.

Predict what the terminal will display after the command saves the script output.
Generate and display the latest saved report by running this command:

./health-report.sh > report.txt && cat report.txt

How Is the Report Saved?

The > operator replaces the contents of report.txt with fresh script output. The && operator continues only after that succeeds.

The cat command prints the saved file to the terminal. This verifies the contents that now live on disk.

You'll see Linux System Health Report followed by all four labeled sections. The displayed content now comes from the saved report.txt file.

Saved Report Missing Content?

Confirm that the command uses one greater-than sign before report.txt.
Confirm that direct execution still prints the complete report.
Confirm that the filename is exactly report.txt.

Help me diagnose an empty or incomplete saved report.

Your Bash reporter is now executable. Your latest system health snapshot is saved in report.txt.

Secret mission

Secret Mission: Filter the Environment with a Pipe

Extend your Bash health reporter with a filtered view of the Linux language environment. You will use a command pipeline to isolate lines containing LANG while preserving every existing report section.

Clean Up Your Resources

Your GitHub Codespaces lab stays free while its use remains within the personal account's monthly quota. Your only cleanup decision is whether to keep the codespace running, stop it for later, or delete it with the project files inside.

Cost warning

Running codespaces consume compute quota. Stopped codespaces retain storage.

A GitHub Free personal account includes 120 hrs of compute each month. It also includes 15 GB-month of storage.

Without a valid payment method, Codespaces use is blocked after the included quota is exhausted. GitHub does not bill beyond the quota in that case.

Choose Pause or Delete if you have finished working today.

Resources you used:

One unpublished GitHub Codespace containing manual-report.txt, health-report.sh, and report.txt.

Keep everything running

No action is needed while you are actively continuing in the terminal.

Leave the codespace running while you continue working.
Stop the codespace as soon as you finish to preserve compute quota.

Closing the browser tab does not stop the codespace. It continues consuming compute quota until it stops.

Pause - I'll come back to this later

Stopping the codespace preserves your files for the next session. Its retained files continue using storage quota.

Return to the GitHub Codespaces page in Google Chrome.
Open the ellipsis menu for the unpublished codespace.
Select Stop codespace.

You have safely paused the lab. Your saved work remains available for the next start.

Delete - I don't want to use this again

Deleting the unpublished codespace is permanent. The codespace stores all three project files, so they disappear with it.

Return to the GitHub Codespaces page in Google Chrome.
Open the ellipsis menu for the unpublished codespace.
Select Delete.
Confirm that the deleted codespace no longer appears on the page.

That completes the cleanup. The codespace no longer retains the project files or consumes quota.

Nice Work!

You did it! Your browser-based Ubuntu Linux lab in GitHub Codespaces now produces a reusable system health report.

You've learned how to:

Launched an isolated Ubuntu administration lab inside your browser. Confirmed its Linux kernel from the integrated terminal.
Built a manual system snapshot covering the filesystem, identity, processes, storage, and memory. Saved that snapshot in manual-report.txt through output redirection.
Turned repeated checks into an executable Bash health reporter. Diagnosed the owner permission barrier. Restored the execute bit before generating report.txt.
Secret Mission: Extended health-report.sh with a command pipeline. Filtered the language environment down to lines containing LANG.

Ready to quiz yourself?